@valancex/cli 0.14.0 → 0.15.0

package/dist/build.js

@@ -1,6 +1,7 @@
 // `vlx build`: the project → a static site in `dist/web/`. The stages, in order: configuration, content, templates, the browser bundle, then one document per page (and a 404 page, a sitemap
 // when the site has a published address). Everything is generated under `.valance/` first; `dist/` holds only what is built.
-import { build as bundle } from "vite";
+import { build as bundle, defaultServerConditions } from "vite";
+import { CONDITION } from "./libraries.js";
 import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
@@ -37,7 +38,9 @@ const buildDesktop = async (root) => {
         logLevel: "warn",
         plugins: [templates(root)],
         cacheDir: join(root, GENERATED_DIR, "cache"),
-        ssr: { noExternal: true, target: "node" },
+        // the desktop engine is one file: everything is bundled, and a library resolves by its `valance` condition (K4)
+        resolve: { conditions: [CONDITION, ...defaultServerConditions] },
+        ssr: { noExternal: true, target: "node", resolve: { conditions: [CONDITION, ...defaultServerConditions] } },
         esbuild: { keepNames: true },
         build: {
             ssr: join(root, GENERATED_DIR, "desktop.ts"),

package/dist/check.js

@@ -1,6 +1,7 @@
 import { AppError } from "./diagnostics.js";
 import { loadAuthor } from "./author.js";
 import { loadConfig } from "./config.js";
+import { librariesOf } from "./libraries.js";
 import { generateContent, generateEntries, generateProgram } from "./emit.js";
 import { createLoader } from "./vite.js";
 const collect = async (into, work) => {
@@ -22,6 +23,8 @@ export const check = async (root) => {
     if (config === undefined) {
         return { diagnostics: problems, pages: 0, components: [] };
     }
+    // a library whose marker is wrong is reported first: when the application cannot even be loaded, it is the likely reason (a package the build does not process)
+    problems.push(...librariesOf(root).problems);
     generateEntries(root, config);
     const content = await collect(problems, () => generateContent(root, config));
     const server = await createLoader(root, config);
@@ -29,7 +32,9 @@ export const check = async (root) => {
         const author = await collect(problems, () => loadAuthor(server, root));
         const failedAuthor = problems.some((each) => each.file === "src/main.ts");
         const components = failedAuthor ? undefined : await collect(problems, () => generateProgram(root, author, config));
-        return { diagnostics: problems, pages: content?.pages.length ?? 0, components: components ?? [] };
+        // (the templates stage reports the same marker problems; once is enough)
+        const once = problems.filter((each, index) => problems.findIndex((other) => other.file === each.file && other.code === each.code && other.message === each.message) === index);
+        return { diagnostics: once, pages: content?.pages.length ?? 0, components: components ?? [] };
     }
     finally {
         await server.close();

package/dist/cli.js

@@ -24,7 +24,8 @@ import { localCli } from "./delegate.js";
 import { dev } from "./dev.js";
 import { defaultRecording, replayFile } from "./replay.js";
 import { AppError, format } from "./diagnostics.js";
-import { detectPackageManager, directoryFor, directoryProblem, execute, nameProblem, runCommand, titleOf } from "./init.js";
+import { detectPackageManager, directoryFor, directoryProblem, execute, install as installDependencies, nameProblem, PACKAGE_MANAGERS, runCommand, titleOf } from "./init.js";
+import { buildLibrary, checkLibrary, scaffoldLibrary } from "./library.js";
 import { DEFAULT_TARGETS, TARGETS } from "./targets.js";
 import { canAsk, canDraw } from "./tty.js";
 const HELP = `vlx <command>
@@ -35,6 +36,8 @@ const HELP = `vlx <command>
   build                            write the site to dist/web/
   check [--json]                   find mistakes in your files without building
   theme check [--json]             check the theme: tokens, recipes, contrast, and what each target applies
+  init library <name>              make a component library: a workspace with the package and a playground
+  library build|check              build a library's dist/ (JavaScript, declarations, templates, styles); check the package
   generate page|component <name>  add a page, or a component (alias: g)
   generate target web|desktop      add a target to the project
   package --desktop                the desktop target as one executable beside its window (unsigned)
@@ -57,8 +60,32 @@ const GENERATE_HELP = `vlx generate <page|component|target> <name>   (alias: vlx
 
 Nothing is overwritten: a name that is taken is refused.
 `;
+const LIBRARY_HELP = `vlx library <build|check> [--json] [--app <dir>]
+
+Run in a library's package directory (the one with the "valance" export condition; \`vlx init library\` makes one).
+
+  vlx library build    dist/: the TypeScript compiled to JavaScript with declarations (the components' contracts are the
+                       types component() gives them), and every .mprx and .css under src/ copied beside it. Templates ship
+                       as source: the application's build compiles them. Needs typescript installed in the library.
+  vlx library check    the package as a consumer's build needs it: the "valance" condition on exports["."] and the file it
+                       names, no other entry a tool without the condition would load, a peer dependency on
+                       @valancex/common, stylesheets that exist and "sideEffects" that keeps them; then the playground
+                       (--app <dir>, default ../../playground, ./playground or ../playground), an application that depends
+                       on this package: it must build every target the package declares and write every template the
+                       package ships, and its own \`vlx check\` problems are reported with the library's.
+
+Exits 0 when there is nothing to say, 1 when there is. --json prints the diagnostics.
+`;
+const INIT_LIBRARY_HELP = `vlx init library <name> [--pm <npm|pnpm|yarn|bun>] [--no-install] [--cli <spec>]
+
+Make a component library: a workspace with packages/<name> (a sample component, written with the portable core, its contract,
+a tsconfig and a package.json that is marked as a library) and playground/ (an application that depends on it and builds
+the web and the desktop). <name> is the package name (acme-ui, @acme/ui); the directory is the name's last part.
+Then: cd <dir>, install, \`vlx library build\` in packages/<name>, \`vlx library check\`, and the playground's \`vlx dev\`.
+`;
 const COMMAND_HELP = {
-    init: INIT_HELP,
+    init: `${INIT_HELP}\n${INIT_LIBRARY_HELP}`,
+    library: LIBRARY_HELP,
     generate: GENERATE_HELP,
     g: GENERATE_HELP,
     replay: "vlx replay <log> [--route changes,update,render] [--json] [--allow-user-data]\n\nPlay a session log (written by vlx dev --record, or one of MESH's conformance logs) against this project's templates by the three routes of the equivalence law, and find the first line where one differs from the log: a tree, an event's outcome, a program or manifest that is not the one recorded. It runs no command and reads no clock. Exits 0 when every route gave what the log recorded, 1 when one did not, 2 when the log cannot be read. A log that holds user data (every recording does: its header says containsUserData) is refused unless you pass --allow-user-data: a divergence prints what was typed and shown.\n",
@@ -142,6 +169,34 @@ const runInit = async (args, cwd) => {
     console.log(`vlx init: next: cd ${answers.dir}${outcome.installed ? "" : ` && ${answers.packageManager} install`} && ${runCommand(answers.packageManager)} dev`);
     return 0;
 };
+const runInitLibrary = async (args, cwd) => {
+    const positional = args.filter((each, index) => !each.startsWith("-") && !["--pm", "--cli"].includes(args[index - 1] ?? ""));
+    const name = positional[0];
+    const manager = option(args, "--pm");
+    if (name === undefined || !/^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(name)) {
+        console.error(`vlx init library: name the package: vlx init library acme-ui (lowercase letters, digits, - . _; or @scope/name)\n\n${INIT_LIBRARY_HELP}`);
+        return 2;
+    }
+    if (manager !== undefined && !PACKAGE_MANAGERS.includes(manager)) {
+        console.error(`vlx init library: --pm is one of ${PACKAGE_MANAGERS.join(", ")}`);
+        return 2;
+    }
+    const dir = directoryFor(name.replace(/^@[^/]+\//, ""), cwd);
+    const problem = directoryProblem(dir);
+    if (problem !== undefined) {
+        console.error(`vlx init library: ${problem}`);
+        return 1;
+    }
+    const answers = { name, dir, packageManager: manager ?? detectPackageManager(), ...(option(args, "--cli") === undefined ? {} : { cli: option(args, "--cli") }) };
+    const files = scaffoldLibrary(answers);
+    console.log(`vlx init library: created ${name} in ${dir} (${files.length} files)`);
+    if (!args.includes("--no-install")) {
+        const ran = await installDependencies(answers);
+        console.log(ran.ok ? "vlx init library: installed" : `vlx init library: the dependencies were not installed (${answers.packageManager} install failed); run it yourself in ${dir}`);
+    }
+    console.log(`vlx init library: next: cd ${dir}/packages/${name.replace(/^@[^/]+\//, "")} && vlx library build && vlx library check`);
+    return 0;
+};
 export const main = async (args, cwd = process.cwd()) => {
     const [command, ...rest] = args;
     // `vlx dev --help` says what dev does and runs nothing (`init` and `generate` answer for themselves below).
@@ -161,6 +216,7 @@ export const main = async (args, cwd = process.cwd()) => {
         command === "package" ||
         command === "check" ||
         command === "theme" ||
+        command === "library" ||
         command === "sync" ||
         command === "generate" ||
         command === "g") {
@@ -178,6 +234,9 @@ export const main = async (args, cwd = process.cwd()) => {
                     console.log(INIT_HELP);
                     return 0;
                 }
+                if (rest[0] === "library") {
+                    return await runInitLibrary(rest.slice(1), cwd);
+                }
                 const parsed = parseInit(rest);
                 if (typeof parsed === "string") {
                     console.error(`vlx init: ${parsed}\n\n${INIT_HELP}`);
@@ -287,6 +346,34 @@ export const main = async (args, cwd = process.cwd()) => {
                 }
                 return result.diagnostics.length === 0 ? 0 : 1;
             }
+            case "library": {
+                const sub = rest[0];
+                if (sub !== "build" && sub !== "check") {
+                    console.error("vlx library: say what: vlx library build | vlx library check [--json] [--app <dir>]");
+                    return 2;
+                }
+                const dir = cwd;
+                const json = rest.includes("--json");
+                const given = option(rest, "--app");
+                const report = (diagnostics) => {
+                    if (json) {
+                        console.log(JSON.stringify({ diagnostics }, null, 2));
+                    }
+                    else {
+                        diagnostics.forEach((each) => console.error(`${each.file}${each.line > 0 ? `:${each.line}` : ""} ${each.code}: ${each.message}`));
+                        console.log(diagnostics.length === 0 ? `vlx library ${sub}: no problems` : `vlx library ${sub}: ${diagnostics.length} problem${diagnostics.length === 1 ? "" : "s"}`);
+                    }
+                    return diagnostics.length === 0 ? 0 : 1;
+                };
+                if (sub === "build") {
+                    const built = buildLibrary(dir);
+                    if (!json && built.diagnostics.length === 0) {
+                        console.log(`vlx library build: dist/ written; ${built.copied.length} template and stylesheet file${built.copied.length === 1 ? "" : "s"} copied as source`);
+                    }
+                    return report(built.diagnostics);
+                }
+                return report(await checkLibrary(dir, given === undefined ? {} : { app: resolve(cwd, given) }));
+            }
             case "theme": {
                 if (rest[0] !== "check") {
                     console.error("vlx theme: say what: vlx theme check [--json]");

package/dist/compile.d.ts

@@ -17,8 +17,16 @@ interface Template {
     readonly source: string;
     readonly builtIn: boolean;
 }
+/** A library component left out of a target's program because its library does not support the target (K5): the tag is reported at each use, once, where the application can act. */
+export interface Excluded {
+    readonly id: string;
+    readonly library: string;
+    readonly supports: ReadonlyArray<string>;
+}
 export interface Templates {
     readonly all: ReadonlyArray<Template>;
+    /** The library components this target leaves out, by tag. */
+    readonly excluded: ReadonlyMap<string, Excluded>;
     /** The declared tree, in `src/main.ts`'s own words. */
     readonly tree: ReadonlyArray<Node>;
 }

package/dist/compile.js

@@ -11,6 +11,7 @@ import { AppError, diagnostic } from "./diagnostics.js";
 import { declarationsOf, declaredOf, linked, nameOf, treeOf } from "./tree.js";
 import { tagsOf } from "./outline.js";
 import { entryOf } from "./contract.js";
+import { idOf, libraryOf, librariesOf } from "./libraries.js";
 import { locateKey } from "./wiring.js";
 import { namesOf, webVocabulary, WHOLE } from "@valancex/common/internal";
 import { checkReferences, checkTemplate } from "./rules.js";
@@ -48,7 +49,26 @@ export const templatesOf = (root, author, vocabulary = webVocabulary, views = BU
     }
     const layout = author?.layout;
     const overrides = author?.override ?? [];
-    const declared = treeOf(layout, overrides, author?.components ?? []);
+    const { libraries } = librariesOf(root);
+    const resolved = author?.resolve ?? {};
+    const overridden = new Set(overrides.map((each) => nameOf(each.template.mprx)));
+    const excluded = new Map();
+    const idFor = (component) => idOf(libraries, root, component.template.mprx, nameOf(component.template.mprx));
+    // The components of this target's program. A library's component is left out when its library does not support this target (K5: one diagnostic at the use, not several inside the library), when the
+    // application's own template of that name replaces it (`override`), and when `resolve` chose another of that name (K14).
+    const components = (author?.components ?? []).filter((each) => {
+        const name = nameOf(each.template.mprx);
+        const library = libraryOf(libraries, root, each.template.mprx);
+        if (library === undefined) {
+            return true;
+        }
+        if (!library.targets.includes(vocabulary.target)) {
+            excluded.set(name, { id: idFor(each), library: library.name, supports: library.targets });
+            return false;
+        }
+        return !overridden.has(name) && (resolved[name] === undefined || resolved[name] === idFor(each));
+    });
+    const declared = treeOf(layout, overrides, components);
     const declarations = declarationsOf(root);
     const problems = [];
     /** Where a template's component is defined: its `component(…)` call, else where it is imported, else the top of the entry file. */
@@ -69,25 +89,41 @@ export const templatesOf = (root, author, vocabulary = webVocabulary, views = BU
     const builtInNames = new Set(found.keys());
     for (const each of overrides) {
         const name = nameOf(each.template.mprx);
-        if (!builtInNames.has(name) && name !== ROOT) {
-            problem(at(each.template.mprx), "override-unknown", `<${name}> is not a built-in component, so there is nothing to override; register it in \`components\` instead`);
+        if (!builtInNames.has(name) &&
+            name !== ROOT &&
+            !(author?.components ?? []).some((other) => nameOf(other.template.mprx) === name && libraryOf(libraries, root, other.template.mprx) !== undefined)) {
+            problem(at(each.template.mprx), "override-unknown", `<${name}> is not a built-in component and no library component in \`components\` has that name, so there is nothing to override; register it in \`components\` instead`);
+        }
+    }
+    for (const [tag, id] of Object.entries(resolved)) {
+        if (!(author?.components ?? []).some((each) => idFor(each) === id)) {
+            const named = (author?.components ?? []).filter((each) => nameOf(each.template.mprx) === tag).map(idFor);
+            problem({ file: ENTRY_FILE, line: 1, column: 1 }, "resolve-unknown", `\`resolve\` says <${tag}> is ${id}, but no component in \`components\` has that id${named.length === 0 ? ` (nothing named ${tag} is listed)` : ` (listed with that name: ${named.join(", ")})`}`);
         }
     }
     // A name is one component. Two files of one name, from anywhere in the definition (two libraries', or a library's and the application's), are an error: the first listed must not win silently
     // (decision K14). A component that is not listed in `override` and is named like a built-in is the same collision, with the built-in.
-    // TODO(K14): qualified ids (`acme-ui/disclosure`) will let a library's component be named and overridden without renaming a file; until then the way out of a collision is to rename one.
-    const listed = declaredOf(layout, overrides, author?.components ?? []);
+    // A library's component is named by its qualified id (`acme-ui/disclosure`) in a diagnostic and in `resolve`; the application's own, by the bare name.
+    const listed = declaredOf(layout, overrides, components);
     const firstOf = new Map();
+    const idOfFile = (file, name) => idOf(libraries, root, file, name);
     for (const each of listed) {
         const first = firstOf.get(each.name);
+        const id = idOfFile(each.file, each.name);
         if (first === undefined) {
-            firstOf.set(each.name, each.file);
-            if (each.role === "component" && builtInNames.has(each.name) && !listed.some((other) => other.role !== "component" && other.name === each.name)) {
-                problem(at(each.file), "template-builtin", `${each.file} is <${each.name}>, which is also a built-in component: list it in \`override\` to replace the built-in, or rename the file so both can be used`);
+            firstOf.set(each.name, { file: each.file, id });
+            if (each.role === "component" &&
+                builtInNames.has(each.name) &&
+                resolved[each.name] !== id &&
+                !listed.some((other) => other.role !== "component" && other.name === each.name)) {
+                problem(at(each.file), "template-builtin", `${id} is <${each.name}>, which is also a built-in component: list your own template of that name in \`override\` to replace the built-in, or choose this one with \`resolve: { ${each.name}: "${id}" }\``);
             }
         }
-        else if (first !== each.file) {
-            problem(at(each.file), "template-duplicate", `${each.file} is also <${each.name}>, like ${first}: a component is named by its file, so the name must be unique; rename one of the files`);
+        else if (first.file !== each.file) {
+            const libraryMade = id !== each.name || first.id !== each.name;
+            problem(at(each.file), "template-duplicate", libraryMade
+                ? `${id === each.name ? each.file : id} and ${first.id === each.name ? first.file : first.id} are both <${each.name}>: a component is named by its file, so the name must be unique; choose one with \`resolve: { ${each.name}: "${id === each.name ? first.id : id}" }\` in defineApp, or replace both with your own template of that name in \`override\``
+                : `${each.file} is also <${each.name}>, like ${first.file}: a component is named by its file, so the name must be unique; rename one of the files`);
         }
     }
     const files = new Map();
@@ -127,7 +163,7 @@ export const templatesOf = (root, author, vocabulary = webVocabulary, views = BU
     if (problems.length > 0) {
         throw new AppError(problems);
     }
-    return { all: [...found.values()], tree };
+    return { all: [...found.values()], tree, excluded };
 };
 /** The templates the root reaches, following the tags each uses. A template nothing uses is not part of the program (the compiler refuses one). */
 const reachable = (all) => {
@@ -253,7 +289,7 @@ const renamedHint = (vocabulary, used, at) => {
 };
 /** Compiles the application's templates against a target's vocabulary (the web's by default). Fails with every diagnostic, each pointing into the file it is about. */
 export const compileViews = async (root, author, vocabulary = webVocabulary, views = BUILT_IN) => {
-    const { all, tree } = templatesOf(root, author, vocabulary, views);
+    const { all, tree, excluded } = templatesOf(root, author, vocabulary, views);
     const used = reachable(all);
     const model = modelOf(root, author, tree, vocabulary);
     if (!used.some((template) => template.component === ROOT)) {
@@ -268,6 +304,18 @@ export const compileViews = async (root, author, vocabulary = webVocabulary, vie
         const found = [
             ...(result.components ?? []).flatMap((entry) => entry.diagnostics.diagnostics
                 .filter((each) => each.severity === "error")
+                .map((each) => {
+                // a library component this target leaves out (K5): one sentence at the use, in place of the compiler's "unknown component"
+                const left = each.code === "unknown-component" ? excluded.get(/component "([^"]+)"/.exec(each.message)?.[1] ?? "") : undefined;
+                return left === undefined
+                    ? each
+                    : {
+                        ...each,
+                        code: "unsupported-target",
+                        message: `<${each.message.match(/component "([^"]+)"/)[1]}> is ${left.id}, and ${left.library} supports ${left.supports.join(" and ")} only; this project builds for ${vocabulary.target}. Use a component that ${vocabulary.target} has, or build ${left.library} for ${vocabulary.target}`,
+                        suggestions: [],
+                    };
+            })
                 .map((each) => diagnostic(each.path, each.span.start.line, each.code, each.message +
                 (each.suggestions.length > 0 ? ` (did you mean ${each.suggestions.map((suggestion) => `"${suggestion.replacement}"`).join(" or ")}?)` : "") +
                 renamedHint(vocabulary, used, each), each.span.start.column))),

package/dist/config.d.ts

@@ -27,6 +27,8 @@ export interface Config {
     /** The size budgets a production build is held to (Tier 2): the project's own, or none, in which case the framework's start-up budgets apply (W14). Never checked by `vlx dev`. */
     readonly budgets: ReadonlyArray<Budget> | undefined;
     /** What `vlx dev --record` leaves out of a session log (Tier 2; R9, R14): nothing, unless the project says. */
+    /** The theme package the project uses instead of the default theme (Tier 2; K12): an installed package whose `valance` field is `{ "kind": "theme" }`. Absent: the `theme/` directory, else the default. */
+    readonly theme: string | undefined;
     readonly record: {
         readonly redact: {
             readonly scope: ReadonlyArray<ReadonlyArray<string>>;

package/dist/config.js

@@ -66,6 +66,9 @@ const url = (value) => {
 const title = (value) => typeof value === "string" && value.includes("{page}") && value.length <= 120 && !/[{}]/.test(value.replaceAll("{page}", "").replaceAll("{site}", ""))
     ? undefined
     : 'must contain "{page}" and may use "{site}", for example "{page} · {site}" (at most 120 characters)';
+const themePackage = (value) => typeof value === "string" && /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(value)
+    ? undefined
+    : 'must be the name of an installed theme package, such as "acme-theme" or "@acme/theme"';
 const flag = (value) => (typeof value === "boolean" ? undefined : "must be true or false");
 const api = (value) => {
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
@@ -128,7 +131,7 @@ export const loadConfig = (root) => {
     const desktop = read(root, DESKTOP_FILE);
     const problems = [
         ...(desktop === undefined ? [] : check(DESKTOP_FILE, desktop.text, desktop.value, { $schema: schema, version }, [])),
-        ...check(PROJECT_FILE, project.text, project.value, { $schema: schema, version, name: text, title, record, budgets: budgetProblems }, ["name"]),
+        ...check(PROJECT_FILE, project.text, project.value, { $schema: schema, version, name: text, title, record, budgets: budgetProblems, theme: themePackage }, ["name"]),
         ...(web === undefined ? [] : check(WEB_FILE, web.text, web.value, { $schema: schema, version, base, url, headers: flag, announce: flag, api }, [])),
     ];
     if (problems.length > 0) {
@@ -143,6 +146,7 @@ export const loadConfig = (root) => {
         web: { base: given.base ?? "/", url: given.url ?? "", headers: given.headers ?? true, announce: given.announce ?? true },
         api: { base: given.api?.base ?? "", proxy: given.api?.proxy ?? "" },
         budgets: named.budgets,
+        theme: named.theme,
         record: { redact: { scope: named.record?.redact.scope ?? [], commands: named.record?.redact.commands ?? [] } },
     };
 };

package/dist/contract.js

@@ -71,6 +71,13 @@ export const entryOf = (declared) => {
         }
     }
     const unit = declared.unit === undefined ? undefined : unitEntry(declared.unit, props, problems);
+    // A controllable field is read in the template by the name of its prop, and the unit supplies that name (the prop's value when the caller writes it, else the unit's own); listing the prop in the scope
+    // as well is `manifest-unit-clash` in MESH, for a field the docs say to declare this way (found building a tabs component outside the repository).
+    for (const [name, each] of Object.entries(unit?.state ?? {})) {
+        if (each.controllable === true) {
+            delete scope[name];
+        }
+    }
     if (declared.name !== undefined) {
         const named = props[declared.name];
         if (named === undefined && !problems.some((each) => each.name === declared.name)) {

package/dist/emit.js

@@ -21,6 +21,7 @@ import { targetOf } from "./targets.js";
 import { forTarget } from "@valancex/common/internal";
 import { AppError } from "./diagnostics.js";
 import { ENTRY_FILE, ensureGeneratedDir, GENERATED_DIR, generated, writeIfChanged } from "./project.js";
+import { librariesOf } from "./libraries.js";
 import { themeOf } from "./theme.js";
 import { buildWiring } from "./wiring.js";
 /** The layout of the portable core on the web: `column` and `row` are custom elements, and this is what they are (`@valancex/common`'s web vocabulary). It is the library's layer, the first of the
@@ -50,6 +51,18 @@ const CORE_CSS = `/* Generated by \`valance\`. The web's realization of the port
 `;
 /** The theme's stylesheet. A theme with a problem is reported by \`check\` (and refused by \`build\`); the page gets no theme meanwhile rather than a half of one. */
 const themeStylesheet = (root) => themeOf(root).css ?? "/* The theme has a problem: run `vlx check`. */\n";
+/**
+ * The stylesheets the libraries declare (K6), in the library layer: below the theme and the application, so a theme or the application's own rule wins without a specificity fight. The web's only (a
+ * window is drawn from the theme's resolved values). Absent when no library declares one.
+ */
+const libraryStylesheet = (root) => {
+    const parts = librariesOf(root).libraries.flatMap((library) => library.styles.map((file) => ({ library, file })));
+    return parts.length === 0
+        ? undefined
+        : `/* Generated by \`valance\`: the stylesheets libraries declare, in the library layer. */\n@layer vlx-library, vlx-theme, vlx-app;\n${parts
+            .map(({ library, file }) => `/* ${library.name}: ${relative(library.dir, file).split(sep).join("/")} */\n@layer vlx-library {\n${readFileSync(file, "utf8")}\n}\n`)
+            .join("")}`;
+};
 /** The stylesheets the web loads: every one under `src/` except those in another target's directory (`src/desktop/`). */
 const stylesheets = (root) => existsSync(join(root, SOURCE_DIR))
     ? readdirSync(join(root, SOURCE_DIR), { recursive: true, encoding: "utf8" })
@@ -64,7 +77,7 @@ const clientSource = (root, config, record = false) => `// Generated by \`valanc
 import { start } from "@valancex/common/client";
 import content from "./content.json";
 import program from "./${programFile(config, "web")}";
-import "./theme.css";
+${libraryStylesheet(root) === undefined ? "" : 'import "./library.css";\n'}import "./theme.css";
 import "./core.css";
 ${hasEntry(root) ? `import author from "../${ENTRY_FILE}";\n` : "const author = undefined;\n"}${stylesheets(root)
     .map((file) => `import "../${file}";\n`)
@@ -128,6 +141,8 @@ export const generateProgram = async (root, author, config, only) => {
             problems.push(...error.diagnostics);
         }
     }
+    // a library whose marker is wrong is reported at its package.json, where its author can act (K5)
+    problems.push(...librariesOf(root).problems);
     // a theme the project writes is checked with the templates: a mistake in it is as much the project's as one in a layout
     problems.push(...(themeOf(root).custom ? themeOf(root).diagnostics : []));
     if (problems.length > 0) {
@@ -194,6 +209,7 @@ export const generateEntries = (root, config, options) => {
             ? [
                 writeIfChanged(generated(root, "core.css"), CORE_CSS),
                 writeIfChanged(generated(root, "theme.css"), themeStylesheet(root)),
+                writeIfChanged(generated(root, "library.css"), libraryStylesheet(root) ?? "/* No library declares a stylesheet. */\n"),
                 writeIfChanged(generated(root, "client.ts"), clientSource(root, config, options?.record === true)),
                 writeIfChanged(generated(root, "server.ts"), serverSource(root, config)),
             ]

package/dist/libraries.d.ts

@@ -0,0 +1,41 @@
+import type { Diagnostic } from "./diagnostics.js";
+import type { TargetId } from "./targets.js";
+/** The export condition that marks a package as a VALANCE library. */
+export declare const CONDITION = "valance";
+export declare const KINDS: readonly ["components", "theme"];
+export type LibraryKind = (typeof KINDS)[number];
+export interface Library {
+    readonly name: string;
+    readonly version: string;
+    /** The package's real directory (a symlink resolved). */
+    readonly dir: string;
+    readonly kind: LibraryKind;
+    /** The targets whose vocabularies the library's templates are written for. Absent in the field: every target. */
+    readonly targets: ReadonlyArray<TargetId>;
+    /** The stylesheets the library declares, as absolute paths of files that exist. */
+    readonly styles: ReadonlyArray<string>;
+    /** A theme's `theme.json`, as an absolute path (kind `theme`). */
+    readonly theme?: string;
+}
+/** Whether an `exports` value has the `valance` condition anywhere in it. */
+export declare const hasCondition: (exports: unknown) => boolean;
+/** The directory `name` is installed in for a project at `root`, looked for as Node looks for it: `node_modules/<name>` here and in each parent directory. */
+export declare const installedAt: (root: string, name: string) => string | undefined;
+/** What reading a project's dependencies found: the libraries, and what is wrong with their markers. */
+export interface Found {
+    readonly libraries: ReadonlyArray<Library>;
+    readonly problems: ReadonlyArray<Diagnostic>;
+}
+/**
+ * The libraries a project at `root` depends on: each dependency (of any kind) installed under `node_modules` whose `exports` has the `valance` condition. A package with the field and no condition is
+ * said so (the build keys on the condition, K11); a field that is wrong is a diagnostic about the package's `package.json`, where its author can act.
+ */
+export declare const librariesOf: (root: string) => Found;
+/** The library a file belongs to (a template or a stylesheet, by absolute or project-relative path), if any. */
+export declare const libraryOf: (libraries: ReadonlyArray<Library>, root: string, file: string) => Library | undefined;
+/** The qualified id of a component: `package/name` for a library's, the bare name for the application's and the built-ins'. */
+export declare const idOf: (libraries: ReadonlyArray<Library>, root: string, file: string, name: string) => string;
+/** What the build tells Vite about marked packages: process them (`noExternal`), and resolve the `valance` condition. */
+export declare const viteSettings: (libraries: ReadonlyArray<Library>) => {
+    readonly names: ReadonlyArray<string>;
+};

package/dist/libraries.js

@@ -0,0 +1,169 @@
+// Libraries of components and themes (Bet 12; decisions K3 to K14). A package is a VALANCE library when its `exports` has the condition `valance`: that condition is the one thing the build keys on
+// (K11). The package's top-level `valance` field is metadata only: what it holds (`components` or `theme`), the targets it supports, the stylesheets it declares. Templates ship as source and the
+// consumer's build compiles them (K3), so the build must process a marked package instead of loading it in Node, which does not know `.mprx` or `.css`.
+//
+// This module reads the project's dependencies and says which are libraries. It does not load them: Vite does, with the settings `viteSettings` returns.
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { diagnostic } from "./diagnostics.js";
+/** The targets a library can name. (Not imported from `targets.ts`, which imports the compiler, which imports this.) */
+const TARGET_IDS = ["web", "desktop"];
+const isTarget = (name) => TARGET_IDS.includes(name);
+/** The export condition that marks a package as a VALANCE library. */
+export const CONDITION = "valance";
+export const KINDS = ["components", "theme"];
+const read = (file) => {
+    try {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Whether an `exports` value has the `valance` condition anywhere in it. */
+export const hasCondition = (exports) => typeof exports === "object" && exports !== null && !Array.isArray(exports) && Object.entries(exports).some(([key, value]) => key === CONDITION || hasCondition(value));
+/** The directory `name` is installed in for a project at `root`, looked for as Node looks for it: `node_modules/<name>` here and in each parent directory. */
+export const installedAt = (root, name) => {
+    for (let at = resolve(root);; at = dirname(at)) {
+        const candidate = join(at, "node_modules", ...name.split("/"));
+        if (existsSync(join(candidate, "package.json"))) {
+            return realpathSync(candidate);
+        }
+        if (dirname(at) === at) {
+            return undefined;
+        }
+    }
+};
+const NONE = { libraries: [], problems: [] };
+/** The metadata a library's `valance` field holds, checked. `file` names the package.json in a diagnostic. */
+const fieldOf = (manifest, dir, file) => {
+    const problems = [];
+    const problem = (code, message) => void problems.push(diagnostic(file, 0, code, message));
+    const field = manifest.valance;
+    const given = typeof field === "object" && field !== null && !Array.isArray(field) ? field : undefined;
+    if (field !== undefined && given === undefined) {
+        problem("library-field", `"valance" in ${file} must be an object ({ "kind": "components", "targets": ["web", "desktop"] })`);
+    }
+    for (const key of Object.keys(given ?? {})) {
+        if (!["kind", "targets", "styles", "theme"].includes(key)) {
+            problem("library-field", `"valance.${key}" in ${file} is not a field of a library (kind, targets, styles, theme)`);
+        }
+    }
+    const kind = given?.["kind"] ?? "components";
+    if (!KINDS.includes(kind)) {
+        problem("library-field", `"valance.kind" in ${file} is ${JSON.stringify(kind)}; it is one of ${KINDS.map((each) => `"${each}"`).join(", ")}`);
+    }
+    const listed = given?.["targets"];
+    const targets = [];
+    if (listed !== undefined && (!Array.isArray(listed) || listed.length === 0)) {
+        problem("library-field", `"valance.targets" in ${file} must be a non-empty list of targets`);
+    }
+    for (const each of Array.isArray(listed) ? listed : []) {
+        if (typeof each === "string" && isTarget(each)) {
+            targets.push(each);
+        }
+        else {
+            problem("library-field", `"valance.targets" in ${file} names ${JSON.stringify(each)}, which is not a target`);
+        }
+    }
+    const styles = [];
+    const listedStyles = Array.isArray(given?.["styles"]) ? given["styles"] : [];
+    for (const each of listedStyles) {
+        const path = typeof each === "string" ? resolve(dir, each) : undefined;
+        if (path === undefined || !path.startsWith(dir + sep)) {
+            problem("library-field", `"valance.styles" in ${file} lists ${JSON.stringify(each)}: a stylesheet inside the package, as "./dist/x.css"`);
+        }
+        else if (!existsSync(path)) {
+            problem("library-styles", `"valance.styles" in ${file} lists ${String(each)}, which the package does not contain (did the library build run?)`);
+        }
+        else {
+            styles.push(path);
+        }
+    }
+    let theme;
+    if (kind === "theme") {
+        const entry = given?.["theme"];
+        const path = typeof entry === "string" ? resolve(dir, entry) : undefined;
+        if (path === undefined || !path.startsWith(dir + sep)) {
+            problem("library-field", `a theme package says where its theme is: "valance": { "kind": "theme", "theme": "./theme/theme.json" } in ${file}`);
+        }
+        else if (!existsSync(path)) {
+            problem("library-field", `"valance.theme" in ${file} is ${String(entry)}, which the package does not contain`);
+        }
+        else {
+            theme = path;
+        }
+    }
+    return {
+        problems,
+        ...(problems.length > 0
+            ? {}
+            : {
+                library: {
+                    name: manifest.name ?? "",
+                    version: manifest.version ?? "0.0.0",
+                    dir,
+                    kind: kind,
+                    targets: targets.length === 0 ? ["web", "desktop"] : targets,
+                    styles,
+                    ...(theme === undefined ? {} : { theme }),
+                },
+            }),
+    };
+};
+/**
+ * The libraries a project at `root` depends on: each dependency (of any kind) installed under `node_modules` whose `exports` has the `valance` condition. A package with the field and no condition is
+ * said so (the build keys on the condition, K11); a field that is wrong is a diagnostic about the package's `package.json`, where its author can act.
+ */
+export const librariesOf = (root) => {
+    const own = read(join(root, "package.json"));
+    if (own === undefined) {
+        return NONE;
+    }
+    const names = [...new Set([...Object.keys(own.dependencies ?? {}), ...Object.keys(own.devDependencies ?? {}), ...Object.keys(own.peerDependencies ?? {})])].sort();
+    const libraries = [];
+    const problems = [];
+    for (const name of names) {
+        const dir = installedAt(root, name);
+        const manifest = dir === undefined ? undefined : read(join(dir, "package.json"));
+        if (dir === undefined || manifest === undefined) {
+            continue;
+        }
+        const marked = hasCondition(manifest.exports);
+        if (!marked) {
+            if (manifest.valance !== undefined && name !== "@valancex/valance") {
+                problems.push(diagnostic(`node_modules/${name}/package.json`, 0, "library-unmarked", `${name} has a "valance" field but no "valance" export condition, so the build does not process it: add ${JSON.stringify({ exports: { ".": { valance: "./dist/index.js" } } })} (the condition is what marks a library)`));
+            }
+            continue;
+        }
+        const checked = fieldOf({ ...manifest, name }, dir, `node_modules/${name}/package.json`);
+        problems.push(...checked.problems);
+        if (checked.library !== undefined) {
+            libraries.push(checked.library);
+            // A library resolves its peers (`@valancex/common`, `effect`) from where it really is. One linked from outside the project (`npm install ../acme-ui`) finds none there (K7).
+            const missing = Object.keys(manifest.peerDependencies ?? {}).filter((peer) => manifest.peerDependenciesMeta?.[peer]?.optional !== true && installedAt(dir, peer) === undefined);
+            if (missing.length > 0) {
+                problems.push(diagnostic(`node_modules/${name}/package.json`, 0, "library-peers", `${name} cannot find its peer ${missing.map((each) => `${each}`).join(", ")} from ${dir}. A library linked from outside the project (\`npm install ../${name}\`) resolves its peers from its own directory: install it from a packed tarball (\`npm pack\`), or develop it in a workspace (\`vlx init library\`)`));
+            }
+        }
+    }
+    return { libraries, problems };
+};
+/** The library a file belongs to (a template or a stylesheet, by absolute or project-relative path), if any. */
+export const libraryOf = (libraries, root, file) => {
+    let real = resolve(root, file);
+    try {
+        real = realpathSync(real);
+    }
+    catch {
+        // a file that does not exist belongs to whoever its path says
+    }
+    return libraries.find((each) => real.startsWith(each.dir + sep));
+};
+/** The qualified id of a component: `package/name` for a library's, the bare name for the application's and the built-ins'. */
+export const idOf = (libraries, root, file, name) => {
+    const library = libraryOf(libraries, root, file);
+    return library === undefined ? name : `${library.name}/${name}`;
+};
+/** What the build tells Vite about marked packages: process them (`noExternal`), and resolve the `valance` condition. */
+export const viteSettings = (libraries) => ({ names: libraries.map((each) => each.name) });

package/dist/library.d.ts

@@ -0,0 +1,32 @@
+import type { Diagnostic } from "./diagnostics.js";
+import type { PackageManager } from "./init.js";
+export interface LibraryAnswers {
+    /** The library's package name (`acme-ui`, `@acme/ui`). */
+    readonly name: string;
+    /** Where the workspace is written: absolute. */
+    readonly dir: string;
+    readonly packageManager: PackageManager;
+    readonly cli?: string;
+}
+/** Every file \`vlx init library\` writes, without writing any: relative path (\`/\` separated) → text. */
+export declare const planLibrary: (answers: LibraryAnswers) => ReadonlyMap<string, string>;
+/** Writes the workspace. Throws if the directory has something in it. Returns the files written. */
+export declare const scaffoldLibrary: (answers: LibraryAnswers) => ReadonlyArray<string>;
+/**
+ * The rules a consumer's build relies on, held at the library where its author can act (K7, K8, K11, K13): the marker, the entry that exists, a peer on `@valancex/common`, no entry Node would load
+ * unmarked, stylesheets that exist and a `sideEffects` that keeps them, and the playground: an application that depends on this package, builds every target the package declares, and uses every
+ * template the package ships (so no template is shipped that no target has checked).
+ */
+export declare const checkLibrary: (dir: string, options?: {
+    readonly app?: string;
+}) => Promise<ReadonlyArray<Diagnostic>>;
+export interface BuiltLibrary {
+    readonly diagnostics: ReadonlyArray<Diagnostic>;
+    /** The files copied beside the compiled JavaScript: templates and stylesheets, relative to `dist/`. */
+    readonly copied: ReadonlyArray<string>;
+}
+/**
+ * Writes `dist/`: the TypeScript compiled to JavaScript with declarations (the contracts of the components are the types `component()` gives them), and every `.mprx` and `.css` under `src/` copied beside
+ * it, because templates ship as source and the consumer's build compiles them (K3). It does not check the package; `vlx library check` does.
+ */
+export declare const buildLibrary: (dir: string) => BuiltLibrary;

package/dist/library.js

@@ -0,0 +1,333 @@
+// The author's side of a library (Bet 12; K7, K8, K13): `vlx init library` makes a workspace (the library, and a playground application that uses it), `vlx library build` writes what is published
+// (JavaScript, declarations, and the templates and stylesheets as source), `vlx library check` holds the package to the rules a consumer's build relies on. The consumer's side (finding a marked
+// package, the build settings, the diagnostics at the use site) is `libraries.ts`.
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { check } from "./check.js";
+import { loadConfig } from "./config.js";
+import { diagnostic } from "./diagnostics.js";
+import { cliSpec, commonSpec, packageName, runCommand } from "./init.js";
+import { CONDITION, hasCondition, installedAt } from "./libraries.js";
+import { themeFileProblems } from "./theme.js";
+const own = () => JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
+const MPRX_D_TS = `// What importing a template file gives TypeScript: the file's address. (The bundler makes the import; see @valancex/common/types/mprx.d.ts.)
+declare module "*.mprx" {
+  const template: { readonly mprx: string };
+  export default template;
+}
+`;
+/** Every file \`vlx init library\` writes, without writing any: relative path (\`/\` separated) → text. */
+export const planLibrary = (answers) => {
+    const out = new Map();
+    const manager = answers.packageManager;
+    const slug = packageName(answers.name.replace(/^@[^/]+\//, ""));
+    const lib = `packages/${slug}`;
+    const common = own().dependencies["@valancex/common"];
+    const range = common === undefined || common.startsWith("workspace:") ? `^${own().version}` : common;
+    const link = manager === "pnpm" ? "workspace:*" : "*";
+    const effect = own().dependencies["effect"] ?? "^3.10.0";
+    const q = '"';
+    out.set("package.json", json({
+        name: `${slug}-workspace`,
+        version: "0.0.0",
+        private: true,
+        type: "module",
+        ...(manager === "pnpm" ? {} : { workspaces: ["packages/*", "playground"] }),
+        scripts: {
+            // each through the package's own script: `vlx` is installed in the package that uses it, not at the workspace root, where a script cannot find it
+            "build:library": `cd ${lib} && ${runCommand(manager)} build`,
+            "check:library": `cd ${lib} && ${runCommand(manager)} check`,
+            playground: `cd playground && ${runCommand(manager)} dev`,
+        },
+    }));
+    if (manager === "pnpm") {
+        out.set("pnpm-workspace.yaml", `packages:\n  - "packages/*"\n  - playground\nallowBuilds:\n  esbuild: false\n`);
+    }
+    out.set(".gitignore", "node_modules\ndist\n.valance\n");
+    out.set(`${lib}/package.json`, json({
+        name: answers.name,
+        version: "0.0.0",
+        description: "A VALANCE component library.",
+        license: "MIT",
+        type: "module",
+        files: ["dist"],
+        // the condition is what marks a library: the consumer's build processes the package instead of loading it in Node, which does not know .mprx or .css (decision K11)
+        exports: { ".": { types: "./dist/index.d.ts", [CONDITION]: "./dist/index.js" } },
+        sideEffects: ["**/*.css"],
+        valance: { kind: "components", targets: ["web", "desktop"] },
+        scripts: { build: "vlx library build", check: "vlx library check" },
+        peerDependencies: { "@valancex/common": range, effect: ">=3.10.0 <4" },
+        devDependencies: { "@types/node": "^22.0.0", "@valancex/cli": cliSpec(manager, answers.cli), "@valancex/common": commonSpec(manager), effect, typescript: "^5.6.0" },
+    }));
+    out.set(`${lib}/tsconfig.json`, json({
+        compilerOptions: {
+            target: "ES2022",
+            module: "ESNext",
+            moduleResolution: "Bundler",
+            lib: ["ES2022", "DOM"],
+            types: ["node"],
+            strict: true,
+            noUncheckedIndexedAccess: true,
+            exactOptionalPropertyTypes: true,
+            skipLibCheck: true,
+            declaration: true,
+            rootDir: "src",
+            outDir: "dist",
+        },
+        include: ["src"],
+    }));
+    out.set(`${lib}/src/mprx.d.ts`, MPRX_D_TS);
+    out.set(`${lib}/src/index.ts`, `// What the library exports: its components, and the list of them an application can pass to \`components\`. Removing an export, a component, a prop or an event is a breaking change (decision K8).
+export { greeting } from "./greeting.js";
+import { greeting } from "./greeting.js";
+
+export const components = [greeting];
+`);
+    out.set(`${lib}/src/greeting.mprx`, `<column>
+  <heading>{title}</heading>
+  <text>{message}</text>
+  <button on.click={dismiss()}>Dismiss</button>
+</column>
+`);
+    out.set(`${lib}/src/greeting.ts`, `import { component } from "@valancex/common";
+import { Schema } from "effect";
+import template from "./greeting.mprx";
+
+// The interface of \`<greeting>\`, stated once, where it is defined. It is built from the portable core (\`column\`, \`heading\`, \`text\`, \`button\`), so it runs on every target the package declares.
+export const greeting = component(template, {
+  props: { title: Schema.String, message: Schema.String },
+  events: { dismiss: Schema.Void },
+});
+`);
+    out.set(`${lib}/README.md`, `# ${answers.name}
+
+A VALANCE component library. Its templates ship as source and the application's build compiles them; the package says so with the \`valance\` export condition, and says what it supports in its \`valance\` field.
+
+\`\`\`
+${runCommand(manager)} build:library   # vlx library build: JavaScript, declarations, templates and stylesheets into dist/
+${runCommand(manager)} check:library   # vlx library check: the package, and the playground that uses every component
+${runCommand(manager)} playground      # the playground application, served
+\`\`\`
+
+The playground (\`../../playground\`) is an application that depends on this package the way a consumer does; it is how each target the package declares is checked.
+`);
+    out.set("playground/package.json", json({
+        name: `${slug}-playground`,
+        version: "0.0.0",
+        private: true,
+        type: "module",
+        scripts: { dev: "vlx dev", build: "vlx build", check: "vlx check", prepare: "vlx sync" },
+        dependencies: { "@valancex/common": commonSpec(manager), effect, [answers.name]: link },
+        devDependencies: { "@types/node": "^22.0.0", "@valancex/cli": cliSpec(manager, answers.cli), typescript: "^5.6.0" },
+    }));
+    out.set("playground/valance.json", json({ $schema: "./node_modules/@valancex/cli/schemas/valance.schema.json", version: 1, name: `${slug} playground` }));
+    out.set("playground/valance.web.json", json({ $schema: "./node_modules/@valancex/cli/schemas/valance.web.schema.json", version: 1 }));
+    out.set("playground/valance.desktop.json", json({ $schema: "./node_modules/@valancex/cli/schemas/valance.desktop.schema.json", version: 1 }));
+    out.set("playground/tsconfig.json", json({
+        compilerOptions: {
+            types: ["node"],
+            target: "ES2022",
+            module: "NodeNext",
+            moduleResolution: "NodeNext",
+            lib: ["ES2022", "DOM"],
+            strict: true,
+            noUncheckedIndexedAccess: true,
+            exactOptionalPropertyTypes: true,
+            skipLibCheck: true,
+            isolatedModules: true,
+            noEmit: true,
+            allowArbitraryExtensions: true,
+            rootDirs: ["src", ".valance/types"],
+        },
+        include: ["src"],
+    }));
+    out.set("playground/.gitignore", "node_modules\ndist\n.valance\n");
+    out.set("playground/content/index.md", `---\ntitle: ${answers.name} playground\n---\n\n# ${answers.name}\n\nEvery component of the library, on every target it declares.\n`);
+    out.set("playground/src/main.ts", `import { component, defineApp, field } from "@valancex/common";
+import { Schema } from "effect";
+import { components } from ${q}${answers.name}${q};
+import layout from "./layout.mprx";
+import desktopLayout from "./desktop/layout.mprx";
+
+// The playground uses the library the way an application does: it lists its components, and a template writes their tags. Each target the library declares has a layout here, so \`vlx library check\`
+// holds every component to every target it says it supports.
+export default defineApp({
+  targets: { desktop: { layout: component(desktopLayout) } },
+  layout: component(layout),
+  components,
+  state: { dismissed: field(Schema.Boolean, false) },
+  commands: (command) => ({ dismiss: command((state) => ({ ...state, dismissed: true })) }),
+});
+`);
+    const layout = `<column>
+  {#if dismissed}
+    <text>Dismissed</text>
+  {:else}
+    <greeting title="Hello" message="This is the playground." on.dismiss={dismiss()} />
+  {/if}
+</column>
+`;
+    out.set("playground/src/layout.mprx", layout);
+    out.set("playground/src/desktop/layout.mprx", layout);
+    return out;
+};
+/** Writes the workspace. Throws if the directory has something in it. Returns the files written. */
+export const scaffoldLibrary = (answers) => {
+    if (existsSync(answers.dir) && readdirSync(answers.dir).filter((each) => each !== ".git").length > 0) {
+        throw new Error(`${answers.dir} is not empty`);
+    }
+    const made = planLibrary(answers);
+    for (const [name, text] of made) {
+        const path = join(answers.dir, ...name.split("/"));
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, text);
+    }
+    return [...made.keys()].sort();
+};
+const FILE = "package.json";
+/** The files under `dir` with `extension`, relative and sorted. */
+const under = (dir, extension) => existsSync(dir)
+    ? readdirSync(dir, { recursive: true, encoding: "utf8" })
+        .map((each) => each.split(sep).join("/"))
+        .filter((each) => each.endsWith(extension) && !each.split("/").includes("node_modules"))
+        .sort()
+    : [];
+/**
+ * The rules a consumer's build relies on, held at the library where its author can act (K7, K8, K11, K13): the marker, the entry that exists, a peer on `@valancex/common`, no entry Node would load
+ * unmarked, stylesheets that exist and a `sideEffects` that keeps them, and the playground: an application that depends on this package, builds every target the package declares, and uses every
+ * template the package ships (so no template is shipped that no target has checked).
+ */
+export const checkLibrary = async (dir, options = {}) => {
+    const problems = [];
+    const problem = (code, message) => void problems.push(diagnostic(FILE, 0, code, message));
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(join(dir, FILE), "utf8"));
+    }
+    catch {
+        return [diagnostic(FILE, 0, "library-package", `there is no ${FILE} in ${dir}: run \`vlx library check\` in the library's package directory`)];
+    }
+    if (!hasCondition(manifest.exports)) {
+        problem("library-unmarked", `${FILE} has no "valance" export condition: add ${JSON.stringify({ exports: { ".": { types: "./dist/index.d.ts", valance: "./dist/index.js" } } })}; the condition is what marks a library`);
+        return problems;
+    }
+    const entry = manifest.exports?.["."];
+    const marked = typeof entry?.[CONDITION] === "string" ? entry[CONDITION] : undefined;
+    if (marked === undefined) {
+        problem("library-entry", `exports["."] needs a "valance" condition that is the file: "valance": "./dist/index.js"`);
+    }
+    else if (!existsSync(resolve(dir, marked))) {
+        problem("library-entry", `exports["."].valance is ${marked}, which does not exist: run \`vlx library build\``);
+    }
+    // Node would load whatever else the entry offers; that is the .mprx failure the condition exists to prevent.
+    for (const key of ["default", "import", "require", "node"]) {
+        const other = entry?.[key];
+        if (other !== undefined && other !== marked) {
+            problem("library-default", `exports["."].${key} is ${JSON.stringify(other)}: a tool that does not know the "valance" condition would load it and meet a template. Remove it, or make it the same file as "valance"`);
+        }
+    }
+    const isTheme = manifest.valance?.kind === "theme";
+    if (!isTheme && manifest.peerDependencies?.["@valancex/common"] === undefined) {
+        problem("library-peer", `${FILE} should declare @valancex/common as a peer dependency (one copy of the framework in an application; removing it from the peers is breaking, K8)`);
+    }
+    const styles = manifest.valance?.styles ?? [];
+    if (styles.length > 0) {
+        const sideEffects = manifest.sideEffects;
+        const keepsCss = Array.isArray(sideEffects) && sideEffects.some((each) => typeof each === "string" && each.includes(".css"));
+        if (sideEffects === true || sideEffects === undefined || keepsCss) {
+            // (true and absent keep every file; a list must name the stylesheets)
+        }
+        else {
+            problem("library-side-effects", `"sideEffects" in ${FILE} drops stylesheets from a bundle: use ["**/*.css"] (K6)`);
+        }
+    }
+    // A theme is data: it is checked as a project's theme is (tokens, recipes, the contrast of the pairs it declares), and needs no playground.
+    if (isTheme) {
+        const file = manifest.valance?.theme === undefined ? undefined : resolve(dir, manifest.valance.theme);
+        if (file === undefined || !existsSync(file)) {
+            problem("library-field", `"valance.theme" in ${FILE} must name the package's theme.json`);
+        }
+        else {
+            problems.push(...themeFileProblems(file, dir));
+        }
+        return problems;
+    }
+    // the playground
+    const app = options.app ?? ["../../playground", "playground", "../playground"].map((each) => resolve(dir, each)).find((each) => existsSync(join(each, FILE)));
+    if (app === undefined) {
+        problem("library-playground", "no playground application was found (../../playground, ./playground or ../playground; or --app <dir>): an application that depends on this package and uses each of its components is how each target it declares is checked");
+        return problems;
+    }
+    const label = relative(dir, app).split(sep).join("/");
+    const config = await (async () => {
+        try {
+            return loadConfig(app);
+        }
+        catch (error) {
+            problem("library-playground", `${label}: ${error instanceof Error ? error.message : String(error)}`);
+            return undefined;
+        }
+    })();
+    if (config === undefined) {
+        return problems;
+    }
+    const declared = manifest.valance?.targets ?? ["web", "desktop"];
+    for (const target of declared) {
+        if (!config.targets.includes(target)) {
+            problem("library-playground-target", `the package declares ${target}, but the playground (${label}) does not build for it: add valance.${target}.json there, so that target is checked`);
+        }
+    }
+    if (installedAt(app, manifest.name ?? "") === undefined) {
+        problem("library-playground", `the playground (${label}) has no ${manifest.name} installed: install the workspace, and run \`vlx library build\` first`);
+        return problems;
+    }
+    const result = await check(app);
+    for (const each of result.diagnostics) {
+        problems.push({ ...each, file: `${label}/${each.file}` });
+    }
+    // every template the package ships is used by the playground: a target it declares has then checked it
+    const shipped = under(resolve(dir, dirname(marked ?? "dist/index.js")), ".mprx").map((each) => basename(each, ".mprx"));
+    const checked = new Set(result.components);
+    for (const name of shipped) {
+        if (!checked.has(name)) {
+            problems.push(diagnostic(`${label}/src/layout.mprx`, 0, "library-unused", `the package ships <${name}>, but the playground's templates never write it, so no target has checked it: use it there`));
+        }
+    }
+    return problems;
+};
+/** The TypeScript compiler of the library's own installation. */
+const tscOf = (dir) => {
+    const installed = installedAt(dir, "typescript");
+    return installed === undefined ? undefined : join(installed, "bin", "tsc");
+};
+/**
+ * Writes `dist/`: the TypeScript compiled to JavaScript with declarations (the contracts of the components are the types `component()` gives them), and every `.mprx` and `.css` under `src/` copied beside
+ * it, because templates ship as source and the consumer's build compiles them (K3). It does not check the package; `vlx library check` does.
+ */
+export const buildLibrary = (dir) => {
+    const src = join(dir, "src");
+    if (!existsSync(src)) {
+        return { diagnostics: [diagnostic("src", 0, "library-source", `there is no src/ in ${dir}: run \`vlx library build\` in the library's package directory`)], copied: [] };
+    }
+    const tsc = tscOf(dir);
+    if (tsc === undefined) {
+        return { diagnostics: [diagnostic(FILE, 0, "library-build", "typescript is not installed here: add it to the library's devDependencies and install")], copied: [] };
+    }
+    // dist/ is made by this build alone: a file left from a component that was renamed or removed would be shipped (and its template checked as if it were a component)
+    rmSync(join(dir, "dist"), { recursive: true, force: true });
+    const ran = spawnSync(process.execPath, [tsc, "-p", join(dir, "tsconfig.json")], { cwd: dir, encoding: "utf8" });
+    if (ran.status !== 0) {
+        const lines = `${ran.stdout}${ran.stderr}`.split("\n").filter((each) => each.trim() !== "");
+        return { diagnostics: lines.map((line) => diagnostic("tsconfig.json", 0, "library-build", line)), copied: [] };
+    }
+    const dist = join(dir, "dist");
+    const copied = [];
+    for (const file of [...under(src, ".mprx"), ...under(src, ".css")]) {
+        mkdirSync(dirname(join(dist, file)), { recursive: true });
+        copyFileSync(join(src, file), join(dist, file));
+        copied.push(file);
+    }
+    return { diagnostics: [], copied };
+};

package/dist/package.js

@@ -1,6 +1,7 @@
 // `vlx package`: the desktop target as something to hand to a person. The engine becomes one executable (Node's single executable application: the engine bundled to one file, with the MESH
 // runtime's module inside as an asset, injected into a `node` binary), set beside the Desktop PORT's window program. Unsigned: signing and notarizing are not done here (the artifacts say so).
-import { build as bundle } from "vite";
+import { build as bundle, defaultServerConditions } from "vite";
+import { CONDITION } from "./libraries.js";
 import { execFileSync } from "node:child_process";
 import { chmodSync, copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
@@ -95,7 +96,9 @@ export const packageDesktop = async (root, options = {}) => {
         logLevel: "warn",
         plugins: [templates(root)],
         cacheDir: join(root, GENERATED_DIR, "cache"),
-        ssr: { noExternal: true, target: "node" },
+        // the desktop engine is one file: everything is bundled, and a library resolves by its `valance` condition (K4)
+        resolve: { conditions: [CONDITION, ...defaultServerConditions] },
+        ssr: { noExternal: true, target: "node", resolve: { conditions: [CONDITION, ...defaultServerConditions] } },
         esbuild: { keepNames: true },
         build: {
             ssr: join(root, GENERATED_DIR, "desktop.sea.ts"),

package/dist/theme.d.ts

@@ -1,10 +1,16 @@
 import type { Diagnostic } from "./diagnostics.js";
 export declare const THEME_DIR = "theme";
-/** The theme file the project uses: its own `theme/theme.json`, else the default theme's. */
+/**
+ * The theme file the project uses: a theme package it names (`"theme": "acme-theme"` in `valance.json`; K12), else its own `theme/theme.json`, else the default theme's. The package's problems (not
+ * installed, not a theme, and a `theme/` directory beside it) are `problems`.
+ */
 export declare const themeFileOf: (root: string) => {
     readonly file: string;
     readonly custom: boolean;
+    readonly problems: ReadonlyArray<Diagnostic>;
 };
+/** The problems of a theme file, checked as a project's theme is (tokens, recipes, contrast of the pairs it declares); `base` is what a file's name is shown relative to. */
+export declare const themeFileProblems: (file: string, base: string) => ReadonlyArray<Diagnostic>;
 export interface ThemeResult {
     readonly custom: boolean;
     readonly name: string;

package/dist/theme.js

@@ -1,24 +1,64 @@
 // The project's theme. A project that writes none has the default theme (Tier 1: nothing to do, and every primitive of the portable core is styled); a project that has a `theme/` directory with a
 // `theme.json` (Tier 2) uses it instead, whole: its token documents by mode and its recipes. A recipe's `escape` block (Tier 3) is the marked way to a CSS property outside the contract, for the web.
 // The stylesheet is compiled here, at build time; nothing is computed in the browser.
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join, relative } from "node:path";
 import { checkTheme, compileWeb, coverageOf, defaultInputs, loadTheme, resolveForDesktop, root as styleRoot } from "@valancex/style";
 import { diagnostic } from "./diagnostics.js";
+import { librariesOf } from "./libraries.js";
 export const THEME_DIR = "theme";
-/** The theme file the project uses: its own `theme/theme.json`, else the default theme's. */
+/** The theme package `valance.json` names, if it names one (read here without the rest of the configuration: `vlx check` reports a wrong `valance.json` itself). */
+const themePackageOf = (root) => {
+    try {
+        const given = JSON.parse(readFileSync(join(root, "valance.json"), "utf8")).theme;
+        return typeof given === "string" ? given : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * The theme file the project uses: a theme package it names (`"theme": "acme-theme"` in `valance.json`; K12), else its own `theme/theme.json`, else the default theme's. The package's problems (not
+ * installed, not a theme, and a `theme/` directory beside it) are `problems`.
+ */
 export const themeFileOf = (root) => {
     const own = join(root, THEME_DIR, "theme.json");
-    return existsSync(own) ? { file: own, custom: true } : { file: join(styleRoot, "themes", "default", "theme.json"), custom: false };
+    const named = themePackageOf(root);
+    const fallback = existsSync(own) ? { file: own, custom: true } : { file: join(styleRoot, "themes", "default", "theme.json"), custom: false };
+    if (named === undefined) {
+        return { ...fallback, problems: [] };
+    }
+    const library = librariesOf(root).libraries.find((each) => each.name === named);
+    if (library === undefined || library.kind !== "theme" || library.theme === undefined) {
+        return {
+            ...fallback,
+            custom: true,
+            problems: [
+                diagnostic("valance.json", 0, "theme-package", `"theme": "${named}" is not an installed theme package: install it, and it must be marked (a "valance" export condition and \`"valance": { "kind": "theme", "theme": "./theme/theme.json" }\`)`),
+            ],
+        };
+    }
+    return {
+        file: library.theme,
+        custom: true,
+        problems: existsSync(own)
+            ? [diagnostic("valance.json", 0, "theme-conflict", `"theme": "${named}" and a theme/ directory are both given: a project has one theme; remove one`)]
+            : [],
+    };
 };
 const asDiagnostic = (each) => diagnostic(each.file, 0, each.code, `${each.path === undefined || each.path === "" ? "" : `${each.path}: `}${each.message}`);
+/** The problems of a theme file, checked as a project's theme is (tokens, recipes, contrast of the pairs it declares); `base` is what a file's name is shown relative to. */
+export const themeFileProblems = (file, base) => {
+    const loaded = loadTheme(file, (path) => relative(base, path).split("\\").join("/"));
+    return checkTheme(loaded, defaultInputs()).problems.map(asDiagnostic);
+};
 /** Loads and checks the project's theme. */
 export const themeOf = (root) => {
-    const { file, custom } = themeFileOf(root);
+    const { file, custom, problems } = themeFileOf(root);
     const loaded = loadTheme(file, (path) => relative(root, path).split("\\").join("/"));
     const inputs = defaultInputs();
     const checked = checkTheme(loaded, inputs);
-    const diagnostics = checked.problems.map(asDiagnostic);
+    const diagnostics = [...problems, ...checked.problems.map(asDiagnostic)];
     return {
         custom,
         name: loaded.theme.name,
@@ -37,7 +77,7 @@ export const themeReport = (root) => {
         custom: themeFileOf(root).custom,
         name: loaded.theme.name,
         modes: Object.keys(loaded.modes),
-        diagnostics: checked.problems.map(asDiagnostic),
+        diagnostics: [...themeFileOf(root).problems, ...checked.problems.map(asDiagnostic)],
         contrast: checked.contrast,
         coverage: ["web", "desktop"].map((target) => coverageOf(loaded, inputs, target)),
     };

package/dist/vite.js

@@ -1,5 +1,6 @@
-import { createLogger, createServer } from "vite";
+import { createLogger, createServer, defaultClientConditions, defaultServerConditions } from "vite";
 import { join, relative, sep } from "node:path";
+import { CONDITION, librariesOf } from "./libraries.js";
 import { GENERATED_DIR, OUTPUT_DIR } from "./project.js";
 export const CLIENT_ENTRY = `${GENERATED_DIR}/client.ts`;
 export const SERVER_ENTRY = `/${GENERATED_DIR}/server.ts`;
@@ -30,7 +31,19 @@ export const templates = (root) => ({
     // The module is only the file's address, so a change to the template changes nothing the browser holds; the rebuild (dev.ts) recompiles it and reloads once, with the overlay if it fails.
     handleHotUpdate: ({ file }) => (file.endsWith(".mprx") ? [] : undefined),
 });
+/**
+ * What marked packages (libraries, K4) need from the bundler: the `valance` export condition resolved, for the browser and for the server, and the packages processed by Vite instead of loaded by
+ * Node, which does not know `.mprx` or `.css`. Added for every project, with nothing to write: a project with no library has no package that has the condition.
+ */
+const librarySettings = (root) => {
+    const names = librariesOf(root).libraries.map((each) => each.name);
+    return {
+        resolve: { conditions: [CONDITION, ...defaultClientConditions] },
+        ssr: { noExternal: names, resolve: { conditions: [CONDITION, ...defaultServerConditions] } },
+    };
+};
 export const baseConfig = (root, config, out = OUTPUT_DIR) => ({
+    ...librarySettings(root),
     root,
     configFile: false,
     base: config.web.base,
@@ -43,7 +56,8 @@ export const baseConfig = (root, config, out = OUTPUT_DIR) => ({
     clearScreen: false,
     build: { outDir: join(root, out), emptyOutDir: true, target: "esnext", manifest: true, rollupOptions: { input: join(root, CLIENT_ENTRY) } },
     // The MESH runtime refers to node:fs/promises on a path the browser never takes.
-    optimizeDeps: { exclude: ["@valancex/mesh-runtime", "@valancex/cli", "@valancex/common"] },
+    // (a library's package is not prebundled either: its templates are the build's to compile)
+    optimizeDeps: { exclude: ["@valancex/mesh-runtime", "@valancex/cli", "@valancex/common", ...librariesOf(root).libraries.map((each) => each.name)] },
 });
 /** A Vite server that serves nothing: it loads the author's TypeScript and the generated server entry in Node. Used by build and check. */
 export const createLoader = async (root, config) => createServer({ ...baseConfig(root, config), optimizeDeps: { noDiscovery: true, include: [] }, server: { middlewareMode: true, hmr: false, watch: null, ws: false } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valancex/cli",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "vlx, the VALANCE command: make an application (vlx init), serve it as you edit (vlx dev), build it to a static site (vlx build), check it (vlx check). Content, layout, components and styles in, a website out.",
   "keywords": [
     "valance",
@@ -56,9 +56,9 @@
     "postject": "1.0.0-alpha.6",
     "react": "19.2.8",
     "vite": "7.3.6",
-    "@valancex/style": "^0.14.0",
-    "@valancex/valance": "^0.14.0",
-    "@valancex/common": "^0.14.0"
+    "@valancex/common": "^0.15.0",
+    "@valancex/style": "^0.15.0",
+    "@valancex/valance": "^0.15.0"
   },
   "devDependencies": {
     "@types/jsdom": "^21.1.7",

package/schemas/valance.schema.json

@@ -64,6 +64,11 @@
         }
       }
     },
+    "theme": {
+      "type": "string",
+      "pattern": "^(@[a-z0-9][a-z0-9._-]*/)?[a-z0-9][a-z0-9._-]*$",
+      "description": "The theme package this project uses in place of the default theme: an installed package whose `valance` field is { \"kind\": \"theme\", \"theme\": \"./theme/theme.json\" }. A project with both this and a `theme/` directory is refused."
+    },
     "budgets": {
       "type": "array",
       "description": "The size budgets `vlx build` holds the production build to (never `vlx dev`). A type, a warning and an error threshold in bytes: 500000, \"500kB\" or \"1MB\" (1 kB is 1,000 bytes). With none, the framework's start-up budgets apply.",