@mapled/cli 0.14.3 → 0.14.4

package/README.md

@@ -50,7 +50,7 @@ Only public values live here — the project id, where the generated types go, t
 npx @mapled/cli types generate
 ```
 
-Reads the project's schema and writes `mapled-types.ts` (the path from `mapled.json`, or `--out <file>`): one interface per collection and single, keyed maps, a `MapledSchema` that ties them together, and doc comments with the field types. Sensitive fields never reach the site and are left out.
+Reads the project's schema and writes `mapled-types.ts` (the path from `mapled.json`, or `--out <file>`): one interface per collection and single, keyed maps, a `MapledSchema` that ties them together, and doc comments with the field types. Sensitive fields never reach the site and are left out. A group field is typed by an interface of its items; the project's component types become one interface each (`HeroComponent`, with `_type: "hero"` and the item's `_key`), a `components` field a list of the union of the types it allows, and `MapledComponent` the union of them all — switch on `_type` to render an item.
 
 ```ts
 import type { MapledSchema } from "./mapled-types";

package/dist/commands.js

@@ -179,7 +179,7 @@ export async function schemaPull(ctx, flags) {
         ctx.out(`${SCHEMA_FILE} is up to date (schema ${pin.hash}).`);
         return;
     }
-    const changes = diffSchema(existing.pin.collections, pin.collections);
+    const changes = diffSchema(existing.pin.collections, pin.collections, { before: existing.pin.componentTypes, after: pin.componentTypes });
     await writePin(found.dir, pin);
     ctx.out(`Updated ${SCHEMA_FILE} (schema ${existing.pin.hash} → ${pin.hash}): ${summarizeChanges(changes).toLowerCase()}.`);
     ctx.out("");
@@ -199,7 +199,7 @@ export async function schemaDiff(ctx, flags) {
         throw new CliError(`No ${SCHEMA_FILE} yet. Run \`mapled schema pull\` to record the schema this site is built against.`);
     }
     const live = pinSchema(await session.get("/v1/agent/schema"), found.config.project);
-    const changes = diffSchema(existing.pin.collections, live.collections);
+    const changes = diffSchema(existing.pin.collections, live.collections, { before: existing.pin.componentTypes, after: live.componentTypes });
     if (flags.json) {
         ctx.out(JSON.stringify({ from: existing.pin.hash, to: live.hash, changes }, null, 2));
     }
@@ -732,8 +732,8 @@ export async function doctor(ctx, flags) {
     checks.push(dr.checkCli(ctx.version, status?.sdk["@mapled/cli"]));
     // the live facts first: the revalidate route's answer matters once a page listens (#435)
     const live = !framework || framework === "nextjs" ? await findLive(dir) : null;
-    checks.push(dr.checkRoute("revalidate", await dr.findRoute(dir, "revalidate"), framework, (live?.listeners.length ?? 0) > 0));
-    checks.push(dr.checkRoute("preview", await dr.findRoute(dir, "preview"), framework));
+    checks.push(dr.checkRoute("revalidate", await dr.findRoute(dir, "revalidate", framework), framework, (live?.listeners.length ?? 0) > 0));
+    checks.push(dr.checkRoute("preview", await dr.findRoute(dir, "preview", framework), framework));
     // the code is read only where the check applies: a Next.js site (or one doctor can't place)
     checks.push(dr.checkLive(live, framework));
     if (status) {

package/dist/doctor.d.ts

@@ -101,6 +101,12 @@ export declare function installedVersion(dir: string, pkg: string): Promise<Pack
 export declare const rendersInBrowser: (framework: string | null | undefined) => boolean;
 /** The first-party package a site of this framework reads through. */
 export declare const sdkOf: (framework: string | null | undefined) => string;
+/** The frameworks whose revalidate and preview routes doctor reads: Next.js
+    (`app/api/mapled/…/route.ts`, `pages/api/mapled/…`), Astro
+    (`src/pages/api/mapled/….ts` — the same paths ROUTE_FILES already names
+    for a Pages Router site under `src/`) and Nuxt (`server/api/mapled/…`,
+    or the module in `nuxt.config.ts`, which mounts them — `moduleRoute`). */
+export declare const checksRoutesOf: (framework: string | null | undefined) => boolean;
 /** How a plain HTML site loads "@mapled/vanilla": a script tag in its
     pages — from a CDN, where the version is in the address, or a copy of
     the single file next to the pages, where it is in the file's first
@@ -152,6 +158,20 @@ export declare function detectFramework(dir: string): Promise<string | undefined
 /** -1, 0 or 1 comparing dotted numeric versions; anything else compares by number. */
 export declare function compareVersions(a: string, b: string): number;
 export type RouteKind = "revalidate" | "preview";
+/** The Nuxt module mounts every route itself: a site whose `nuxt.config`
+    lists "@mapled/nuxt/module" has them without a file. What `findRoute`
+    answers for such a site, when no route file of its own is found. */
+export declare const NUXT_CONFIG_FILES: string[];
+export declare const NUXT_MODULE = "@mapled/nuxt/module";
+export declare function moduleRoute(dir: string): Promise<RouteFile | null>;
+/** Whether a nuxt.config's text lists the module, routes on, in its
+    `modules` array: as the string "@mapled/nuxt/module" or as the
+    identifier a default import of it binds, bare or as the first element
+    of a tuple whose options don't say `routes: false`. Comments don't
+    count; neither does an import that never reaches `modules`.
+    Conservative: a config that can't be read this way claims nothing,
+    and doctor asks for the route files. */
+export declare function mountsModuleRoutes(text: string): boolean;
 export declare const ROUTE_HANDLER: Record<RouteKind, string>;
 /** `cacheMark` and `fetchCache` — the revalidate route only (revalidateRouteFacts). */
 export type RouteFile = {
@@ -160,7 +180,7 @@ export type RouteFile = {
     cacheMark?: boolean;
     fetchCache?: boolean;
 };
-export declare function findRoute(dir: string, kind: RouteKind): Promise<RouteFile | null>;
+export declare function findRoute(dir: string, kind: RouteKind, framework?: string | null): Promise<RouteFile | null>;
 /** GET the site's preview route without a token — the adapter answers 400. */
 export declare function probePreview(origin: string, previewPath: string, f: Fetch): Promise<{
     status: number | null;

package/dist/doctor.js

@@ -113,7 +113,19 @@ export async function installedVersion(dir, pkg) {
     keys are the ones Mapled knows by (lib/siteStack.ts of the API). */
 export const rendersInBrowser = (framework) => framework === "react-spa" || framework === "plain-html";
 /** The first-party package a site of this framework reads through. */
-export const sdkOf = (framework) => !framework || framework === "nextjs" ? "@mapled/next" : framework === "react-spa" ? "@mapled/react" : framework === "plain-html" ? "@mapled/vanilla" : "@mapled/client";
+export const sdkOf = (framework) => !framework || framework === "nextjs" ? "@mapled/next" : framework === "react-spa" ? "@mapled/react" : framework === "plain-html" ? "@mapled/vanilla" : framework === "astro" ? "@mapled/astro" : framework === "nuxt" ? "@mapled/nuxt" : "@mapled/client";
+/** The frameworks whose revalidate and preview routes doctor reads: Next.js
+    (`app/api/mapled/…/route.ts`, `pages/api/mapled/…`), Astro
+    (`src/pages/api/mapled/….ts` — the same paths ROUTE_FILES already names
+    for a Pages Router site under `src/`) and Nuxt (`server/api/mapled/…`,
+    or the module in `nuxt.config.ts`, which mounts them — `moduleRoute`). */
+export const checksRoutesOf = (framework) => !framework || framework === "nextjs" || framework === "astro" || framework === "nuxt";
+/** where the adapter's handlers come from, and where the route file goes, by framework */
+const adapterOf = (framework, kind) => framework === "astro"
+    ? { server: '"@mapled/astro/server"', file: `src/pages/api/mapled/${kind}.ts` }
+    : framework === "nuxt"
+        ? { server: '"@mapled/nuxt/server"', file: `server/api/mapled/${kind}.${kind === "revalidate" ? "post" : "get"}.ts` }
+        : { server: '"@mapled/next/server"', file: `app/api/mapled/${kind}/route.ts` };
 const SKIPPED_DIRS = new Set(["node_modules", ".git", ".next", ".vercel", ".netlify", "vendor"]);
 export async function findScriptTag(dir, site) {
     // pages first, breadth first, and not forever: a site's pages sit near its root
@@ -444,20 +456,116 @@ const ROUTE_FILES = {
         "src/app/api/mapled/revalidate/route",
         "pages/api/mapled/revalidate",
         "src/pages/api/mapled/revalidate",
+        // Nuxt: a Nitro route, with or without the method in its name
+        "server/api/mapled/revalidate.post",
+        "server/api/mapled/revalidate",
     ],
     preview: [
         "app/api/mapled/preview/route",
         "src/app/api/mapled/preview/route",
         "pages/api/mapled/preview",
         "src/pages/api/mapled/preview",
+        "server/api/mapled/preview.get",
+        "server/api/mapled/preview",
     ],
 };
+/** The Nuxt module mounts every route itself: a site whose `nuxt.config`
+    lists "@mapled/nuxt/module" has them without a file. What `findRoute`
+    answers for such a site, when no route file of its own is found. */
+export const NUXT_CONFIG_FILES = ["nuxt.config.ts", "nuxt.config.mts", "nuxt.config.js", "nuxt.config.mjs"];
+export const NUXT_MODULE = "@mapled/nuxt/module";
+export async function moduleRoute(dir) {
+    for (const file of NUXT_CONFIG_FILES) {
+        let text;
+        try {
+            text = await readFile(path.join(dir, file), "utf8");
+        }
+        catch {
+            continue;
+        }
+        return mountsModuleRoutes(text) ? { file: `${file} (${NUXT_MODULE} mounts it)`, usesAdapter: true, cacheMark: true } : null;
+    }
+    return null;
+}
+/** Whether a nuxt.config's text lists the module, routes on, in its
+    `modules` array: as the string "@mapled/nuxt/module" or as the
+    identifier a default import of it binds, bare or as the first element
+    of a tuple whose options don't say `routes: false`. Comments don't
+    count; neither does an import that never reaches `modules`.
+    Conservative: a config that can't be read this way claims nothing,
+    and doctor asks for the route files. */
+export function mountsModuleRoutes(text) {
+    // comments go: block comments, and line comments that aren't the `//` of a URL
+    const code = text.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:])\/\/.*$/gm, "$1");
+    // the names a default import of the module binds
+    const names = [...code.matchAll(/import\s+([A-Za-z_$][\w$]*)\s*(?:,\s*\{[^}]*\})?\s*from\s*["'`]@mapled\/nuxt\/module["'`]/g)].map((m) => m[1]);
+    const open = code.search(/\bmodules\s*:\s*\[/);
+    if (open < 0)
+        return false;
+    const array = balanced(code, code.indexOf("[", open));
+    if (array === null)
+        return false;
+    // each element of the array, at depth one
+    for (const element of elementsOf(array)) {
+        const asString = /^\s*["'`]@mapled\/nuxt\/module["'`]\s*$/.test(element);
+        const asName = names.some((n) => new RegExp(`^\\s*${n.replace(/\$/g, "\\$")}\\s*$`).test(element));
+        if (asString || asName)
+            return true;
+        const tuple = element.trim().startsWith("[") ? balanced(element, element.indexOf("[")) : null;
+        if (tuple === null)
+            continue;
+        const [first, ...options] = elementsOf(tuple);
+        const firstIs = first !== undefined && (/^\s*["'`]@mapled\/nuxt\/module["'`]\s*$/.test(first) || names.some((n) => first.trim() === n));
+        if (!firstIs)
+            continue;
+        return !/\broutes\s*:\s*false\b/.test(options.join(","));
+    }
+    return false;
+}
+/** the text inside the bracket at `at` and its match, or null when unbalanced */
+function balanced(code, at) {
+    const pairs = { "[": "]", "{": "}", "(": ")" };
+    const stack = [];
+    for (let i = at; i < code.length; i++) {
+        const c = code[i];
+        if (c in pairs)
+            stack.push(pairs[c]);
+        else if (c === "]" || c === "}" || c === ")") {
+            if (stack.pop() !== c)
+                return null;
+            if (stack.length === 0)
+                return code.slice(at + 1, i);
+        }
+    }
+    return null;
+}
+/** the comma-separated elements of a bracket's inside, at its own depth */
+function elementsOf(inside) {
+    const out = [];
+    let depth = 0;
+    let from = 0;
+    for (let i = 0; i < inside.length; i++) {
+        const c = inside[i];
+        if (c === "[" || c === "{" || c === "(")
+            depth += 1;
+        else if (c === "]" || c === "}" || c === ")")
+            depth -= 1;
+        else if (c === "," && depth === 0) {
+            out.push(inside.slice(from, i));
+            from = i + 1;
+        }
+    }
+    const last = inside.slice(from);
+    if (last.trim())
+        out.push(last);
+    return out;
+}
 const ROUTE_EXTENSIONS = [".ts", ".tsx", ".js", ".mjs", ".jsx"];
 export const ROUTE_HANDLER = {
     revalidate: "createRevalidateHandler",
     preview: "createPreviewHandler",
 };
-export async function findRoute(dir, kind) {
+export async function findRoute(dir, kind, framework) {
     for (const base of ROUTE_FILES[kind]) {
         for (const ext of ROUTE_EXTENSIONS) {
             const rel = base + ext;
@@ -472,7 +580,7 @@ export async function findRoute(dir, kind) {
             return kind === "revalidate" ? { file: rel, usesAdapter, ...revalidateRouteFacts(text) } : { file: rel, usesAdapter };
         }
     }
-    return null;
+    return framework === "nuxt" ? moduleRoute(dir) : null;
 }
 /** GET the site's preview route without a token — the adapter answers 400. */
 export async function probePreview(origin, previewPath, f) {
@@ -656,22 +764,23 @@ export function checkRoute(kind, found, framework, listens = false) {
                 : "Not needed: the client trades Mapled's preview link on the page itself.",
         };
     }
-    if (framework && framework !== "nextjs") {
+    if (!checksRoutesOf(framework)) {
         return { key, label, status: "skipped", detail: `No ${kind} route check for ${framework} sites yet.` };
     }
+    const adapter = adapterOf(framework, kind);
     if (!found) {
         return kind === "revalidate"
             ? {
                 key,
                 label,
                 status: "failed",
-                detail: `app/api/mapled/revalidate/route.ts is missing — mount ${handler} from "@mapled/next/server".`,
+                detail: `${adapter.file} is missing — mount ${handler} from ${adapter.server}.`,
             }
             : {
                 key,
                 label,
                 status: "warning",
-                detail: `app/api/mapled/preview/route.ts is missing — mount ${handler} from "@mapled/next/server" so Preview from Mapled works.`,
+                detail: `${adapter.file} is missing — mount ${handler} from ${adapter.server} so Preview from Mapled works.`,
             };
     }
     if (kind === "revalidate" && listens && !found.usesAdapter && !found.cacheMark) {
@@ -679,7 +788,7 @@ export function checkRoute(kind, found, framework, listens = false) {
             key,
             label,
             status: "warning",
-            detail: `${found.file} doesn't use ${handler} and doesn't answer with cacheMark() — the release route then names no release, so open tabs don't follow Publish. Use ${handler} from "@mapled/next/server", or answer with the header x-mapled-cache: await cacheMark().`,
+            detail: `${found.file} doesn't use ${handler} and doesn't answer with cacheMark() — the release route then names no release, so open tabs don't follow Publish. Use ${handler} from ${adapter.server}, or answer with the header x-mapled-cache: await cacheMark().`,
         };
     }
     if (kind === "revalidate" && listens && found.fetchCache) {
@@ -691,7 +800,7 @@ export function checkRoute(kind, found, framework, listens = false) {
         };
     }
     if (!found.usesAdapter) {
-        return { key, label, status: "warning", detail: `${found.file} exists but doesn't use ${handler} from "@mapled/next/server".` };
+        return { key, label, status: "warning", detail: `${found.file} exists but doesn't use ${handler} from ${adapter.server}.` };
     }
     return { key, label, status: "passed", detail: found.file };
 }

package/dist/pin.d.ts

@@ -1,4 +1,4 @@
-import { type Schema, type SchemaCollection } from "./schema.js";
+import { type Schema, type SchemaCollection, type SchemaComponentType } from "./schema.js";
 /** mapled/schema.json — the repository's pin of the schema it was last
     synced with (§21.5). `mapled schema diff` compares it with the live
     schema and says which changes a site that READS the content must
@@ -9,6 +9,8 @@ export type SchemaPin = {
     project: string;
     hash: string;
     collections: SchemaCollection[];
+    /** the component types (§45.4) — only when the project has some, so older pins read as before */
+    componentTypes?: SchemaComponentType[];
 };
 /** The schema reduced to what the pin keeps — the live answer of
     GET /v1/agent/schema without ids, positions and counters. */
@@ -22,7 +24,8 @@ export declare function writePin(dir: string, pin: SchemaPin): Promise<string>;
 export type Severity = "breaking" | "safe";
 export type ChangeOp = "added" | "removed" | "changed" | "renamed";
 export type SchemaChange = {
-    scope: "collection" | "field" | "subfield";
+    /** `component`: a component type (§45.4) — `collection` holds its key */
+    scope: "collection" | "field" | "subfield" | "component";
     collection: string;
     collectionName: string;
     /** The field key; "group.sub" for a sub-field. */
@@ -37,7 +40,10 @@ export type SchemaChange = {
     (§33.5) is safe while the old one is still an alias of the field —
     the site keeps reading it — and the rest of the field is compared
     under its new key; once the alias is removed it is a removed field. */
-export declare function diffSchema(before: SchemaCollection[], after: SchemaCollection[]): SchemaChange[];
+export declare function diffSchema(before: SchemaCollection[], after: SchemaCollection[], componentTypes?: {
+    before?: SchemaComponentType[];
+    after?: SchemaComponentType[];
+}): SchemaChange[];
 /** The diff as terminal lines: one heading per collection, one line per
     change, the severity in the last column. */
 export declare function formatChanges(changes: SchemaChange[], paint?: (severity: Severity, text: string) => string): string[];

package/dist/pin.js

@@ -50,6 +50,10 @@ function pinField(f) {
     // translation is part of the schema hash too (§28.2)
     if (f.localized === true)
         out.localized = true;
+    // and so are the component types a field allows (§45.4)
+    if (f.type === "components" && f.components) {
+        out.components = { allowed: [...f.components.allowed], min: f.components.min ?? null, max: f.components.max ?? null };
+    }
     if (f.aliases && f.aliases.length > 0)
         out.aliases = [...f.aliases];
     return out;
@@ -65,7 +69,10 @@ export function pinSchema(schema, project) {
         mode: c.mode,
         fields: c.fields.map(pinField),
     }));
-    return { project, hash: schemaHash({ collections }), collections };
+    const componentTypes = (schema.componentTypes ?? []).map((t) => ({ key: t.key, displayName: t.displayName, fields: t.fields.map(pinSubField) }));
+    if (componentTypes.length === 0)
+        return { project, hash: schemaHash({ collections }), collections };
+    return { project, hash: schemaHash({ collections, componentTypes }), collections, componentTypes };
 }
 export function parsePin(raw, file) {
     let data;
@@ -84,7 +91,8 @@ export function parsePin(raw, file) {
         collections.some((c) => !c || typeof c !== "object" || typeof c.key !== "string" || !Array.isArray(c.fields))) {
         throw new CliError(`${file} isn't a schema pin written by \`mapled schema pull\` — delete it and pull again.`);
     }
-    return pinSchema({ collections: collections }, obj.project);
+    const componentTypes = Array.isArray(obj.componentTypes) ? obj.componentTypes : undefined;
+    return pinSchema({ collections: collections, ...(componentTypes ? { componentTypes } : {}) }, obj.project);
 }
 export async function readPin(dir) {
     const file = path.join(dir, SCHEMA_FILE);
@@ -109,6 +117,9 @@ function describeType(f, names) {
         const target = names.get(f.relation.target) ?? f.relation.target;
         return `relation to ${target}${f.relation.cardinality === "many" ? " (many)" : ""}`;
     }
+    if (f.type === "components" && "components" in f && f.components) {
+        return `components of ${f.components.allowed.join(", ")}`;
+    }
     if (f.type === "group" && "group" in f && f.group) {
         return `group of ${f.group.fields.length} field${f.group.fields.length === 1 ? "" : "s"}${f.group.repeatable ? ", repeatable" : ""}`;
     }
@@ -155,7 +166,7 @@ function sameJson(a, b) {
     (§33.5) is safe while the old one is still an alias of the field —
     the site keeps reading it — and the rest of the field is compared
     under its new key; once the alias is removed it is a removed field. */
-export function diffSchema(before, after) {
+export function diffSchema(before, after, componentTypes = {}) {
     const changes = [];
     const names = new Map();
     for (const c of before)
@@ -252,6 +263,19 @@ export function diffSchema(before, after) {
                     });
                 }
             }
+            // §45.4: a type the list may no longer hold leaves the site's union; a new one is an item the site doesn't render yet
+            if (bf.type === "components" && af.type === "components" && bf.components && af.components) {
+                for (const k of bf.components.allowed)
+                    if (!af.components.allowed.includes(k))
+                        push("changed", `no longer holds ${q(k)} components`, "breaking");
+                for (const k of af.components.allowed)
+                    if (!bf.components.allowed.includes(k))
+                        push("changed", `may hold ${q(k)} components now`, "safe");
+                const limit = (lo, hi) => [lo ? `at least ${lo}` : null, hi ? `up to ${hi}` : null].filter((x) => x !== null).join(", ") || "no item limit";
+                if ((bf.components.min ?? null) !== (af.components.min ?? null) || (bf.components.max ?? null) !== (af.components.max ?? null)) {
+                    push("changed", `${limit(bf.components.min, bf.components.max)} → ${limit(af.components.min, af.components.max)} items`, "safe");
+                }
+            }
             if (!sameJson(bf.validation, af.validation))
                 push("changed", "validation changed", "safe");
             if (!sameJson(bf.defaultValue, af.defaultValue))
@@ -282,6 +306,48 @@ export function diffSchema(before, after) {
             severity: "safe",
         });
     }
+    // the component types (§45.4): an item of a type is typed by the type's sub-fields
+    const typesBefore = componentTypes.before ?? [];
+    const typesAfter = componentTypes.after ?? [];
+    const afterTypes = new Map(typesAfter.map((t) => [t.key, t]));
+    const beforeTypes = new Map(typesBefore.map((t) => [t.key, t]));
+    for (const bt of typesBefore) {
+        const at = afterTypes.get(bt.key);
+        const base = { collection: bt.key, collectionName: `${at?.displayName ?? bt.displayName} (component)` };
+        if (!at) {
+            changes.push({ ...base, scope: "component", op: "removed", detail: "component type removed", severity: "breaking" });
+            continue;
+        }
+        if (bt.displayName !== at.displayName)
+            changes.push({ ...base, scope: "component", op: "changed", detail: `name ${q(bt.displayName)} → ${q(at.displayName)}`, severity: "safe" });
+        const afterSubs = new Map(at.fields.map((s) => [s.key, s]));
+        const beforeSubs = new Map(bt.fields.map((s) => [s.key, s]));
+        for (const bs of bt.fields) {
+            const as = afterSubs.get(bs.key);
+            if (!as) {
+                changes.push({ ...base, scope: "component", field: bs.key, op: "removed", detail: `removed — ${describeType(bs, names)}`, severity: "breaking" });
+                continue;
+            }
+            diffCommon(bs, as, names, (op, detail, severity) => changes.push({ ...base, scope: "component", field: bs.key, op, detail, severity }));
+        }
+        for (const as of at.fields) {
+            if (beforeSubs.has(as.key))
+                continue;
+            changes.push({ ...base, scope: "component", field: as.key, op: "added", detail: `added — ${describeType(as, names)}, ${as.required ? "required" : "optional"}`, severity: "safe" });
+        }
+    }
+    for (const at of typesAfter) {
+        if (beforeTypes.has(at.key))
+            continue;
+        changes.push({
+            collection: at.key,
+            collectionName: `${at.displayName} (component)`,
+            scope: "component",
+            op: "added",
+            detail: `new component type — ${at.fields.length} field${at.fields.length === 1 ? "" : "s"}`,
+            severity: "safe",
+        });
+    }
     return changes;
 }
 const GLYPH = { added: "+", removed: "-", changed: "~", renamed: ">" };
@@ -303,14 +369,14 @@ export function formatChanges(changes, paint = (_, t) => t) {
     for (const key of order) {
         const list = byCollection.get(key);
         const name = list[0].collectionName;
-        const whole = list.find((c) => c.scope === "collection" && c.op !== "changed");
+        const whole = list.find((c) => (c.scope === "collection" || (c.scope === "component" && !c.field)) && c.op !== "changed");
         if (whole) {
             lines.push(`${GLYPH[whole.op]} ${name} (${key})  ${whole.detail.padEnd(detailWidth)}  ${paint(whole.severity, whole.severity)}`);
             continue;
         }
         lines.push(`${name} (${key})`);
         for (const c of list) {
-            const label = c.scope === "collection" ? "(collection)" : c.field;
+            const label = c.scope === "collection" ? "(collection)" : c.scope === "component" && !c.field ? "(component)" : c.field;
             lines.push(`  ${GLYPH[c.op]} ${label.padEnd(width)}  ${c.detail.padEnd(detailWidth)}  ${paint(c.severity, c.severity)}`);
         }
     }

package/dist/schema.d.ts

@@ -44,6 +44,20 @@ export type SchemaField = {
     /** Translated (§28.2): the field holds a value per language; the site
         reads the default language's. Absent on older servers. */
     localized?: boolean;
+    /** Components (§45.4): the component types the field allows (keys of
+        `componentTypes`) and how many items it takes. Only on a components field. */
+    components?: {
+        allowed: string[];
+        min?: number | null;
+        max?: number | null;
+    } | null;
+};
+/** A component type (§45.4): the key an item names in `_type`, the name,
+    the sub-fields in a group's shape. */
+export type SchemaComponentType = {
+    key: string;
+    displayName: string;
+    fields: SchemaSubField[];
 };
 export type SchemaCollection = {
     key: string;
@@ -55,6 +69,8 @@ export type SchemaCollection = {
 };
 export type Schema = {
     collections: SchemaCollection[];
+    /** the project's component types, in their order — absent on older servers */
+    componentTypes?: SchemaComponentType[];
 };
 /** Twelve hex characters over everything the generated types depend on. */
 export declare function schemaHash(schema: Schema): string;

package/dist/schema.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 /** Twelve hex characters over everything the generated types depend on. */
 export function schemaHash(schema) {
-    const projection = schema.collections.map((c) => ({
+    const collections = schema.collections.map((c) => ({
         key: c.key,
         displayName: c.displayName,
         kind: c.kind,
@@ -33,7 +33,31 @@ export function schemaHash(schema) {
             ...(f.type === "computed" && f.computed ? { computed: { expression: f.computed.expression, resultType: f.computed.resultType } } : {}),
             // present only for translated fields, so schemas without translations hash as before
             ...(f.localized === true ? { localized: true } : {}),
+            // present only for components fields (§45.4)
+            ...(f.type === "components" && f.components
+                ? { components: { allowed: [...f.components.allowed], min: f.components.min ?? null, max: f.components.max ?? null } }
+                : {}),
         })),
     }));
+    // the component types (§45.4) join the projection only when the project
+    // has some: the generated types name their sub-fields; a schema without
+    // them hashes as before
+    const projection = schema.componentTypes && schema.componentTypes.length > 0
+        ? {
+            collections,
+            componentTypes: schema.componentTypes.map((t) => ({
+                key: t.key,
+                displayName: t.displayName,
+                fields: t.fields.map((s) => ({
+                    key: s.key,
+                    displayName: s.displayName,
+                    type: s.type,
+                    required: s.required,
+                    options: s.options ?? null,
+                    sensitive: s.sensitive === true,
+                })),
+            })),
+        }
+        : collections;
     return createHash("sha256").update(JSON.stringify(projection)).digest("hex").slice(0, 12);
 }

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import { type Schema, type SchemaCollection } from "./schema.js";
+import { type Schema, type SchemaCollection, type SchemaComponentType } from "./schema.js";
 /** TypeScript types for the content a site reads through @mapled/next:
     one interface per collection and single, plus keyed maps. Sensitive
     fields never reach the site, so they are left out. */
@@ -16,9 +16,25 @@ export declare function singular(word: string): string;
 export declare function pascal(words: string[]): string;
 /** `blog-posts` → `BlogPost`; singles keep their name (`homepage` → `Homepage`). */
 export declare function typeName(key: string, kind: "collection" | "single"): string;
+/** The names the file declares itself — no collection or component type
+    may take one: `mapled-schemas` is a collection like any other, and a
+    component keyed `mapled` isn't the union of them all. */
+export declare const RESERVED_NAMES: readonly ["MapledAssetId", "MapledRecordId", "MapledJson", "MapledLocation", "MapledComponent", "MapledCollections", "MapledSingles", "MapledCollectionKey", "MapledSingleKey", "MapledSchema"];
+/** Every name the file declares, claimed once: the reserved ones first,
+    then the collections', the component types' and the group items' —
+    a name already claimed gets a numeric suffix, whoever asks second. */
+export declare class DeclaredNames {
+    private readonly taken;
+    claim(name: string): string;
+}
 /** Unique type names: the singular PascalCase of the key; the raw
-    PascalCase when two keys meet there; a numeric suffix as a last resort. */
-export declare function typeNames(collections: SchemaCollection[]): Map<string, string>;
+    PascalCase when two keys meet there; a numeric suffix as a last resort
+    — and when the name is one the file declares itself (`RESERVED_NAMES`). */
+export declare function typeNames(collections: SchemaCollection[], declared?: DeclaredNames): Map<string, string>;
+/** Unique names of the component types (§45.4): the PascalCase of the
+    key with `Component` after it, a numeric suffix when that is claimed
+    already — by a collection, another type or the file itself. */
+export declare function componentNames(types: SchemaComponentType[], declared: DeclaredNames): Map<string, string>;
 export declare function generateTypes(schema: Schema, opts?: {
     projectName?: string;
     sdk?: string;

package/dist/types.js

@@ -118,8 +118,8 @@ function renderSubField(sub) {
 /** The field's line, followed by one per previous key (§33.5): a
     renamed field is still delivered under them, typed as the field, and
     the editor strikes them through until the site stops reading them. */
-function renderField(field, owner, names, extras) {
-    const { required, rendered } = renderedField(field, owner, names, extras);
+function renderField(field, owner, names, extras, components, declared) {
+    const { required, rendered } = renderedField(field, owner, names, extras, components, declared);
     const lines = [fieldLine(field.key, field.displayName, required, rendered)];
     for (const alias of field.aliases ?? []) {
         lines.push(`  /** @deprecated Renamed to "${comment(field.key)}" — still delivered under this key until the alias is removed in Mapled. */\n` +
@@ -127,7 +127,7 @@ function renderField(field, owner, names, extras) {
     }
     return lines.join("\n");
 }
-function renderedField(field, owner, names, extras) {
+function renderedField(field, owner, names, extras, components = new Map(), declared = new DeclaredNames()) {
     if (field.type === "relation" && field.relation) {
         const target = names.get(field.relation.target) ?? field.relation.target;
         const many = field.relation.cardinality === "many";
@@ -137,7 +137,8 @@ function renderedField(field, owner, names, extras) {
         };
     }
     if (field.type === "group" && field.group) {
-        const itemName = `${owner}${pascal(wordsOf(field.key))}${field.group.repeatable ? "Item" : ""}`;
+        // the group's interface is a declared name like any other: a component or a collection may have taken it
+        const itemName = declared.claim(`${owner}${pascal(wordsOf(field.key))}${field.group.repeatable ? "Item" : ""}`);
         const kept = field.group.fields.filter((s) => s.sensitive !== true);
         const hidden = field.group.fields.filter((s) => s.sensitive === true).map((s) => s.key);
         const lines = kept.map(renderSubField);
@@ -153,38 +154,95 @@ function renderedField(field, owner, names, extras) {
     if (field.type === "computed" && field.computed) {
         return { required: false, rendered: computedType(field.computed.resultType) };
     }
+    // components (§45.4): a list of the types the field allows, told apart by `_type`
+    if (field.type === "components" && field.components) {
+        const allowed = field.components.allowed.map((k) => components.get(k)).filter((n) => n !== undefined);
+        const union = allowed.length === 0 ? "never" : allowed.length === 1 ? allowed[0] : `(${allowed.join(" | ")})`;
+        const limits = [
+            ...(field.components.min ? [`at least ${field.components.min}`] : []),
+            ...(field.components.max ? [`up to ${field.components.max}`] : []),
+        ];
+        const note = `components${limits.length > 0 ? `, ${limits.join(", ")} items` : ""}${field.localized === true ? ", translated" : ""}`;
+        return { required: field.required, rendered: { type: `${union}[]`, note } };
+    }
     const scalar = scalarType(field.type, field.options);
     // translated (§28.2): one language per read — `locale` on the read picks it
     return { required: field.required, rendered: field.localized === true ? { ...scalar, note: `${scalar.note}, translated` } : scalar };
 }
+/** The names the file declares itself — no collection or component type
+    may take one: `mapled-schemas` is a collection like any other, and a
+    component keyed `mapled` isn't the union of them all. */
+export const RESERVED_NAMES = [
+    "MapledAssetId",
+    "MapledRecordId",
+    "MapledJson",
+    "MapledLocation",
+    "MapledComponent",
+    "MapledCollections",
+    "MapledSingles",
+    "MapledCollectionKey",
+    "MapledSingleKey",
+    "MapledSchema",
+];
+/** Every name the file declares, claimed once: the reserved ones first,
+    then the collections', the component types' and the group items' —
+    a name already claimed gets a numeric suffix, whoever asks second. */
+export class DeclaredNames {
+    taken = new Set(RESERVED_NAMES);
+    claim(name) {
+        let unique = name;
+        for (let n = 2; this.taken.has(unique); n++)
+            unique = `${name}${n}`;
+        this.taken.add(unique);
+        return unique;
+    }
+}
 /** Unique type names: the singular PascalCase of the key; the raw
-    PascalCase when two keys meet there; a numeric suffix as a last resort. */
-export function typeNames(collections) {
+    PascalCase when two keys meet there; a numeric suffix as a last resort
+    — and when the name is one the file declares itself (`RESERVED_NAMES`). */
+export function typeNames(collections, declared = new DeclaredNames()) {
     const preferred = collections.map((c) => typeName(c.key, c.kind));
     const counts = new Map();
     for (const name of preferred)
         counts.set(name, (counts.get(name) ?? 0) + 1);
-    const taken = new Set();
     const out = new Map();
     collections.forEach((c, i) => {
         let name = preferred[i];
         if ((counts.get(name) ?? 0) > 1)
             name = pascal(wordsOf(c.key));
-        let unique = name;
-        for (let n = 2; taken.has(unique); n++)
-            unique = `${name}${n}`;
-        taken.add(unique);
-        out.set(c.key, unique);
+        out.set(c.key, declared.claim(name));
     });
     return out;
 }
+/** Unique names of the component types (§45.4): the PascalCase of the
+    key with `Component` after it, a numeric suffix when that is claimed
+    already — by a collection, another type or the file itself. */
+export function componentNames(types, declared) {
+    const out = new Map();
+    for (const t of types)
+        out.set(t.key, declared.claim(`${pascal(wordsOf(t.key))}Component`));
+    return out;
+}
+/** One interface per component type: `_type` as its key, `_key` the
+    item's own id, then its sub-fields. */
+function renderComponent(type, name) {
+    const lines = [
+        `  /** The component's type */\n  _type: ${JSON.stringify(type.key)};`,
+        "  /** The item's own id — stays with it across saves */\n  _key: string;",
+        ...type.fields.map(renderSubField),
+    ];
+    return `/** ${comment(type.displayName)} — a component (key "${comment(type.key)}") */\nexport interface ${name} {\n${lines.join("\n")}\n}`;
+}
 export function generateTypes(schema, opts = {}) {
     // the package the site reads through: "@mapled/next" unless the framework says otherwise
     const sdk = opts.sdk ?? "@mapled/next";
     // a React app's assetUrl comes from the client its hooks are built on; the HTML runtime has none to call
     const assets = sdk === "@mapled/react" || sdk === "@mapled/vanilla" ? "@mapled/client" : sdk;
     const hash = schemaHash(schema);
-    const names = typeNames(schema.collections);
+    const declared = new DeclaredNames();
+    const names = typeNames(schema.collections, declared);
+    const componentTypes = schema.componentTypes ?? [];
+    const components = componentNames(componentTypes, declared);
     const blocks = [];
     blocks.push([
         `// Types of the published content this site reads through ${sdk}.`,
@@ -198,12 +256,19 @@ export function generateTypes(schema, opts = {}) {
         "export type MapledJson = Record<string, unknown> | unknown[];",
         "export type MapledLocation = { lat: number; lng: number };",
     ].join("\n"));
+    // the component types come first: a components field names them
+    for (const t of componentTypes)
+        blocks.push(renderComponent(t, components.get(t.key)));
+    if (componentTypes.length > 0) {
+        blocks.push("/** Any component of the project — switch on `_type` to render an item of a components field. */\n" +
+            `export type MapledComponent = ${componentTypes.map((t) => components.get(t.key)).join(" | ")};`);
+    }
     for (const c of schema.collections) {
         const name = names.get(c.key);
         const extras = [];
         const kept = c.fields.filter((f) => !f.sensitive);
         const hidden = c.fields.filter((f) => f.sensitive).map((f) => f.key);
-        const lines = kept.map((f) => renderField(f, name, names, extras));
+        const lines = kept.map((f) => renderField(f, name, names, extras, components, declared));
         if (hidden.length > 0)
             lines.push(`  // Sensitive, never delivered: ${comment(hidden.join(", "))}`);
         const traits = [

package/dist/vanillaDigests.js

@@ -12,4 +12,5 @@ export const VANILLA_DIGESTS = {
     "0.2.0": "sha384-HJ5XG9AhAlbKe6jPRVaef3whiVup/5WhprMwqC6RwWhpq6Pb0OsRLzbLmLJ8WH0f",
     "0.2.1": "sha384-6apTHYxXrozzwFCqNU+70Z9pa/FDnhArNomcKQNWbeKRX4scjFiOc9d7wWKCOvTU",
     "0.2.2": "sha384-lfhwQoPUtrbLcD2HXSLr2o1z+aUAjotB62i3LFMGxzBlK5lfCQPQPLOoWL+1DBMc",
+    "0.2.3": "sha384-SuKH/yk2hpNI+Ec2QGKpZ7jVxe+0Ep0x/fchL560g+XuzG5hnVCIhG9OKX6BKdpY",
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapled/cli",
-  "version": "0.14.3",
+  "version": "0.14.4",
   "description": "Mapled CLI — sign in, link a project, generate TypeScript types for its content, create forms, preview drafts and check the site's integration.",
   "license": "MIT",
   "homepage": "https://mapled.io",