@valancex/cli 0.13.0 → 0.15.0

package/dist/contract.d.ts

@@ -7,6 +7,7 @@ export interface Entry {
     readonly props: Readonly<Record<string, {
         readonly type: MeshType;
         readonly required: boolean;
+        readonly default?: unknown;
     }>>;
     readonly events: Readonly<Record<string, {
         readonly payload?: MeshType;
@@ -14,12 +15,28 @@ export interface Entry {
     readonly commands: Readonly<Record<string, never>>;
     /** Every prop is a name the template reads: the same name and type, absent when the prop may be. */
     readonly scope: Readonly<Record<string, MeshType>>;
+    /** The state and commands of one occurrence, when the component has a unit: their names join the scope and the commands in the model. */
+    readonly unit?: {
+        readonly state: Readonly<Record<string, {
+            readonly type: MeshType;
+            readonly default: unknown;
+            readonly controllable?: boolean;
+        }>>;
+        readonly commands: Readonly<Record<string, {
+            readonly parameters: ReadonlyArray<{
+                readonly name: string;
+                readonly type: MeshType;
+            }>;
+        }>>;
+    };
 }
 /** A schema with no model type, said at the declaration. */
 export interface Problem {
-    readonly kind: "props" | "events";
+    readonly kind: "props" | "events" | "unit";
     readonly name: string;
     readonly reason: string;
+    /** The whole message, for a problem that is not a missing type. */
+    readonly message?: string;
 }
 /** What a schema is in the model: put in a struct, so the rules are state's. A field that may be `undefined` comes back optional. */
 export declare const typeOf: (schema: SchemaOf) => MeshType;

package/dist/contract.js

@@ -1,5 +1,6 @@
 import { manifest } from "@valancex/valance/web/build";
 import { Schema } from "effect";
+import { isField, isSnippet } from "@valancex/common";
 /** What a schema is in the model: put in a struct, so the rules are state's. A field that may be `undefined` comes back optional. */
 export const typeOf = (schema) => {
     const derived = manifest({ primitives: {}, scopes: { contract: Schema.Struct({ value: schema }) }, commands: () => ({}) });
@@ -17,11 +18,39 @@ export const entryOf = (declared) => {
     const props = {};
     const scope = {};
     const events = {};
-    for (const [name, schema] of Object.entries(declared.props)) {
+    for (const [name, declaration] of Object.entries(declared.props)) {
         try {
+            if (isSnippet(declaration)) {
+                // A piece of template: a prop of the component and a name its template reads (`{@render name(…)}`). It is not data, so it has no default and is never absent.
+                if (name === "children" && declaration.params.length > 0) {
+                    throw new Error("`children` is the content between the component's tags, so it takes no parameters: write `snippet()`");
+                }
+                const params = declaration.params.map((schema) => {
+                    const type = typeOf(schema);
+                    return type.kind === "optional" ? type.type : type;
+                });
+                const type = { kind: "snippet", params };
+                // An optional one is `snippet<…>?` in the scope too: the template renders it only where `has(name)` says it is there.
+                props[name] = declaration.isOptional ? { type: { kind: "optional", type }, required: false } : { type, required: true };
+                scope[name] = declaration.isOptional ? { kind: "optional", type } : type;
+                continue;
+            }
+            if (name === "children") {
+                throw new Error("`children` is reserved for the content between the component's tags: declare it `snippet()`");
+            }
+            const schema = isField(declaration) ? declaration.schema : declaration;
             const type = typeOf(schema);
             const optional = type.kind === "optional";
-            props[name] = { type: optional ? type.type : type, required: !optional };
+            if (isField(declaration)) {
+                // A default is for a component that has a template (the model applies it to those only) and is written as the schema encodes it. The prop may then be left out.
+                if (!Schema.is(schema)(declaration.initial)) {
+                    throw new Error("its default is not a value of its type");
+                }
+                props[name] = { type: optional ? type.type : type, required: false, default: Schema.encodeSync(schema)(declaration.initial) };
+            }
+            else {
+                props[name] = { type: optional ? type.type : type, required: !optional };
+            }
             scope[name] = type;
         }
         catch (error) {
@@ -41,5 +70,65 @@ export const entryOf = (declared) => {
             problems.push({ kind: "events", name, reason: reasonOf(error) });
         }
     }
-    return { entry: { props, events, commands: {}, scope }, problems };
+    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)) {
+            problems.push({ kind: "props", name: declared.name, reason: "", message: `"${declared.name}" is declared as the component's name (\`name\`) but is not one of its props` });
+        }
+        else if (named !== undefined && (named.type.kind !== "string" || !named.required)) {
+            problems.push({
+                kind: "props",
+                name: declared.name,
+                reason: "",
+                message: `the prop "${declared.name}" is the component's name (\`name\`), so it must be a string every use writes: \`Schema.String\`, with no default and not optional`,
+            });
+        }
+    }
+    return { entry: { props, events, commands: {}, scope, ...(unit === undefined ? {} : { unit }) }, problems };
+};
+/** The model's `unit` of a component: each state field with its type and default, each command with its parameters. A field whose schema has no model type is a problem at the declaration. */
+const unitEntry = (declared, props, problems) => {
+    const state = {};
+    const commands = {};
+    for (const [name, field] of Object.entries(declared.fields)) {
+        try {
+            const type = typeOf(field.schema);
+            const controllable = declared.controllable.includes(name);
+            if (!Schema.is(field.schema)(field.initial)) {
+                throw new Error("its default is not a value of its type");
+            }
+            if (controllable && props[name] === undefined) {
+                throw new Error("it is `controllable`, so the component must declare a prop of the same name (optional, of the same type) for the caller to own it with");
+            }
+            state[name] = {
+                type: type.kind === "optional" ? type.type : type,
+                default: Schema.encodeSync(field.schema)(field.initial),
+                ...(controllable ? { controllable: true } : {}),
+            };
+        }
+        catch (error) {
+            problems.push({ kind: "unit", name, reason: reasonOf(error) });
+        }
+    }
+    for (const [name, command] of Object.entries(declared.commands)) {
+        try {
+            const parameters = Object.entries(command.input?.fields ?? {}).map(([parameter, schema]) => {
+                const type = typeOf(schema);
+                return { name: parameter, type: type.kind === "optional" ? type.type : type };
+            });
+            commands[name] = { parameters };
+        }
+        catch (error) {
+            problems.push({ kind: "unit", name, reason: reasonOf(error) });
+        }
+    }
+    return { state, commands };
 };

package/dist/dev.d.ts

@@ -5,6 +5,11 @@ export interface DevOptions {
     readonly target?: TargetId;
     readonly port?: number;
     readonly host?: string;
+    /**
+     * Record the session (`--record`): the file the page's log is appended to (`@valancex/valance/replay`; read it with `vlx replay`). A development feature, never uploaded: a log holds
+     * what the person typed. The generated page entry that records is rewritten without it by the next run that does not ask for it.
+     */
+    readonly record?: string;
     /** Called with each report (a rebuild, a mistake); defaults to the console. */
     readonly log?: (line: string) => void;
     /** Called with every mistake still open, after the first build and after each rebuild: empty when the project is sound. */

package/dist/dev.js

@@ -1,5 +1,20 @@
+// `vlx dev`: the project served from memory and from disk, rebuilt as its authored files change. Built on a Vite server for what Vite is good at (serving modules, style updates without a
+// reload, the error overlay); everything else is this file's: each page is rendered on the server with the same code a build uses, so development shows what production will.
+//
+// What each change does:
+//
+//   content/**               the content is rebuilt; the browser reloads
+//   src/**/*.mprx, src/main.ts   the templates are recompiled (the manifest derives from main.ts); the browser reloads
+//   src/**/*.css             the style is replaced in the open page, no reload
+//   public/**                the browser reloads
+//   adding or removing a stylesheet or src/main.ts   the entries are rewritten; the browser reloads
+//   valance.json, valance.web.json   the server restarts (the name and the base are fixed when it starts)
+//
+// A mistake in any of them leaves the last good build serving, and is shown in the terminal and as an overlay in the page, naming the file and line. Fixing it reloads the page.
+import { recordingNotice } from "./recording-guard.js";
 import { createServer } from "vite";
-import { relative, sep } from "node:path";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname, relative, sep } from "node:path";
 import { loadAuthor } from "./author.js";
 import { loadConfig, PROJECT_FILE, WEB_FILE } from "./config.js";
 import { AppError, format } from "./diagnostics.js";
@@ -51,7 +66,10 @@ const start = async (root, config, options, restart) => {
         });
     const failed = new Map();
     let pending = Promise.resolve();
-    generateEntries(root, config);
+    generateEntries(root, config, { record: options.record !== undefined });
+    if (options.record !== undefined) {
+        recordingNotice(root, options.record, config).forEach(log);
+    }
     const base = baseConfig(root, config);
     const server = await createServer({
         ...base,
@@ -67,29 +85,45 @@ const start = async (root, config, options, restart) => {
             ...(base.plugins ?? []),
             {
                 name: "valance",
-                configureServer: (vite) => () => {
-                    // After Vite's own middleware: modules, styles, public files and the client have had their chance. What is left is a page.
-                    vite.middlewares.use((request, response, next) => {
-                        void (async () => {
-                            // Vite has already removed the base from `request.url`; the application's addresses include it.
-                            const url = new URL(request.originalUrl ?? request.url ?? "/", "http://localhost");
-                            if ((request.method !== "GET" && request.method !== "HEAD") || !url.pathname.startsWith(config.web.base) || /\.[A-Za-z0-9]+$/.test(url.pathname)) {
-                                next();
-                                return;
-                            }
-                            try {
-                                const { render } = (await vite.ssrLoadModule(SERVER_ENTRY));
-                                const { status, html } = await render(url.pathname, { script: `${config.web.base}${GENERATED_DIR}/client.ts`, styles: [] });
-                                response.statusCode = status;
-                                response.setHeader("content-type", "text/html; charset=utf-8");
-                                response.end(await vite.transformIndexHtml(url.pathname, html));
-                            }
-                            catch (error) {
-                                vite.ssrFixStacktrace(error);
-                                next(error);
-                            }
-                        })();
-                    });
+                configureServer: (vite) => {
+                    if (options.record !== undefined) {
+                        const file = options.record;
+                        mkdirSync(dirname(file), { recursive: true });
+                        // the page's recorder posts each line of its log here, in order
+                        vite.middlewares.use("/__vlx/record", (request, response) => {
+                            const chunks = [];
+                            request.on("data", (chunk) => chunks.push(chunk));
+                            request.on("end", () => {
+                                appendFileSync(file, `${Buffer.concat(chunks).toString("utf8")}\n`);
+                                response.statusCode = 204;
+                                response.end();
+                            });
+                        });
+                    }
+                    return () => {
+                        // After Vite's own middleware: modules, styles, public files and the client have had their chance. What is left is a page.
+                        vite.middlewares.use((request, response, next) => {
+                            void (async () => {
+                                // Vite has already removed the base from `request.url`; the application's addresses include it.
+                                const url = new URL(request.originalUrl ?? request.url ?? "/", "http://localhost");
+                                if ((request.method !== "GET" && request.method !== "HEAD") || !url.pathname.startsWith(config.web.base) || /\.[A-Za-z0-9]+$/.test(url.pathname)) {
+                                    next();
+                                    return;
+                                }
+                                try {
+                                    const { render } = (await vite.ssrLoadModule(SERVER_ENTRY));
+                                    const { status, html } = await render(url.pathname, { script: `${config.web.base}${GENERATED_DIR}/client.ts`, styles: [] });
+                                    response.statusCode = status;
+                                    response.setHeader("content-type", "text/html; charset=utf-8");
+                                    response.end(await vite.transformIndexHtml(url.pathname, html));
+                                }
+                                catch (error) {
+                                    vite.ssrFixStacktrace(error);
+                                    next(error);
+                                }
+                            })();
+                        });
+                    };
                 },
             },
         ],
@@ -115,7 +149,7 @@ const start = async (root, config, options, restart) => {
         };
         const wasFailing = failed.size > 0;
         if (stages.includes("entries")) {
-            generateEntries(root, config);
+            generateEntries(root, config, { record: options.record !== undefined });
         }
         if (stages.includes("content")) {
             await run("content", () => generateContent(root, config));

package/dist/emit.d.ts

@@ -13,4 +13,6 @@ export declare const generateProgram: (root: string, author: DefinedApp | undefi
 /** The declaration of one template's type: its props and events as the names TypeScript checks a contract's keys against. */
 export declare const templateType: (props: ReadonlyArray<string>, events: ReadonlyArray<string>) => string;
 /** The entries; rewritten when `src/main.ts` or a stylesheet is added or removed. Each target has its own: the web's two (`client.ts`, `server.ts`), the desktop's one (`desktop.ts`). */
-export declare const generateEntries: (root: string, config?: Config) => boolean;
+export declare const generateEntries: (root: string, config?: Config, options?: {
+    readonly record?: boolean;
+}) => boolean;

package/dist/emit.js

@@ -21,22 +21,48 @@ 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 comes first, so a project's own styles win. */
+/** 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
+ *  three (library, theme, application): a theme's gap replaces the default here, and a project's own styles, which are in no layer, win over both. */
 const CORE_CSS = `/* Generated by \`valance\`. The web's realization of the portable core's layout components. */
-vlx-column {
-  display: flex;
-  flex-direction: column;
-  gap: 0.5rem;
-}
+@layer vlx-library, vlx-theme, vlx-app;
+
+@layer vlx-library {
+  vlx-column {
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+  }
+
+  vlx-row {
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    gap: 0.5rem;
+  }
 
-vlx-row {
-  display: flex;
-  flex-direction: row;
-  align-items: center;
-  gap: 0.5rem;
+  /* Until the application has started (H5) a control the person can see does not yet do anything: say so, so they do not tap it again. */
+  [data-vlx="starting"] :is(button, input, select, textarea, summary, [role="button"], label) {
+    cursor: progress;
+  }
 }
 `;
+/** 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" })
@@ -46,20 +72,22 @@ const stylesheets = (root) => existsSync(join(root, SOURCE_DIR))
         .map((file) => `${SOURCE_DIR}/${file}`)
     : [];
 export const hasEntry = (root) => existsSync(join(root, ENTRY_FILE));
-const clientSource = (root, config) => `// Generated by \`valance\`. Do not edit: it is rewritten whenever the project changes.
+const clientSource = (root, config, record = false) => `// Generated by \`valance\`. Do not edit: it is rewritten whenever the project changes.
 // @ts-nocheck
 import { start } from "@valancex/common/client";
 import content from "./content.json";
 import program from "./${programFile(config, "web")}";
+${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`)
     .join("")}
-await start({ content, program, author });
+${record ? `// \`vlx dev --record\`: development only. A build rewrites this entry without it.\nconst { recording } = await import("@valancex/common/record");\nconst record = recording(program, ${JSON.stringify(config?.record.redact ?? { scope: [], commands: [] })});\n` : ""}await start({ content, program, author${record ? ", record" : ""} });
 `;
 const desktopSource = (root, config) => `// Generated by \`valance\`. Do not edit: it is rewritten whenever the project changes.
 // @ts-nocheck
 import { start } from "@valancex/common/desktop";
+import theme from "./theme.desktop.json";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import content from "./content.json";
@@ -69,7 +97,7 @@ ${hasEntry(root) ? `import author from "../${ENTRY_FILE}";\n` : "const author =
 const wasm = new Uint8Array(readFileSync(new URL("./mesh-runtime.wasm", import.meta.url)));
 // (and the project's public/ files, which images are drawn from)
 const assets = fileURLToPath(new URL("./public/", import.meta.url));
-await start({ content, program, author, wasm, assets });
+await start({ content, program, author, wasm, assets, theme: theme ?? undefined });
 // the window is closed: nothing the application left open keeps the engine alive
 process.exit(0);
 `;
@@ -113,6 +141,10 @@ 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) {
         throw new AppError(problems);
     }
@@ -169,17 +201,24 @@ const writeTemplateTypes = (root, all) => {
     }
 };
 /** The entries; rewritten when `src/main.ts` or a stylesheet is added or removed. Each target has its own: the web's two (`client.ts`, `server.ts`), the desktop's one (`desktop.ts`). */
-export const generateEntries = (root, config) => {
+export const generateEntries = (root, config, options) => {
     ensureGeneratedDir(root);
     const targets = config?.targets ?? ["web"];
     return [
         ...(targets.includes("web")
             ? [
                 writeIfChanged(generated(root, "core.css"), CORE_CSS),
-                writeIfChanged(generated(root, "client.ts"), clientSource(root, config)),
+                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)),
             ]
             : []),
-        ...(targets.includes("desktop") ? [writeIfChanged(generated(root, "desktop.ts"), desktopSource(root, config))] : []),
+        ...(targets.includes("desktop")
+            ? [
+                writeIfChanged(generated(root, "theme.desktop.json"), `${JSON.stringify(themeOf(root).desktop ?? null)}\n`),
+                writeIfChanged(generated(root, "desktop.ts"), desktopSource(root, config)),
+            ]
+            : []),
     ].some(Boolean);
 };

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) });