@mapled/cli 0.14.3 → 0.14.5

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";
@@ -206,7 +206,7 @@ Mapled doctor — Dolphin Landing
 1 warning.
 ```
 
-The repository side: the link, the sign-in, the generated types, the schema pin, the site manifest (and whether it matches what was pushed), the integration hash — one line saying whether the pin and the manifest here describe the same integration Mapled holds, and if not, what moved (the schema, the bindings, or edits made in Mapled) and which command catches up — `MAPLED.md` (and whether it is what Mapled would render now), `MAPLED_KEY` and `MAPLED_WEBHOOK_SECRET` in your env files (names only — values are never read out), env files or Mapled secrets tracked by git, the installed `@mapled/next` and CLI versions, the revalidation and preview routes of a Next.js site, and its live updates — ○ «Not used» while no page mounts `<MapledLive />` or calls `watchRelease`, ✓ when the route they ask answers its `GET` with `createReleaseHandler` (`GET` is the handler, or always returns its call: every return is that call, the last statement is one, and nothing throws), ⚠ when it is missing (the tabs would poll a 404) with the file to add, when the route's `GET` isn't seen to answer with the handler (exported as `POST` they would get a 405; a `GET` that only mentions it, calls it and returns something else, or answers something else on another branch, answers without the release), or when no route can be checked against the endpoint — it is relative to the page, a full address (the tab asks it as written, and doctor can't tell it's the site's own), computed, or comes from spread props; a path from the site's root is checked against the route the App Router picks for it, dynamic and catch-all folders included, among route files with the site's page extensions (`pageExtensions` in next.config; `tsx`, `ts`, `jsx`, `js` by default) and under its `basePath`; ⚠ too when a page of either router, more specific than the route, takes that path first, when the dynamic route that answers sets `dynamicParams`, when the route may set `dynamic` to anything but `"auto"` or `"force-dynamic"` (a copy Next builds without the tab's request), sets `"force-dynamic"` while `createReleaseHandler` there isn't seen to keep a `revalidate` above 0 (its default does; with `false` or `0` Next reads the release past the cache tag) or `fetchCache` to anything but `"auto"` (the release read past the cache tag, before the webhook refreshes the pages), when next.config sets `output: "export"` (no server runs the route), or when next.config may set `pageExtensions`, `basePath` or `output` where doctor can't read them — it reads them only as literals, once, in the object the file exports, and only while the file is declarative: type imports, declarations of data, one export of the config object itself, and functions only as Next's hooks (`webpack`, `headers` …) in it. A module the file loads (a plugin such as `withMDX`, a `path` helper, an env check), a config exported as a function, any other code, a spread or a getter leaves the config unread. With a `basePath`, a listener that gives no endpoint asks under it from `@mapled/next` 0.10.0 — doctor reads the version the site has installed, and it's a ⚠ when that is older or missing. A `middleware` file (`proxy` in Next 16) next to the folder Next reads is a ⚠ unless its matcher, read the way Next's build reads `export const config`, surely leaves the route's path alone: it has no matcher, doctor can't read it, a source may take the path, or next.config has locales (`i18n`). `src/app` or `src/pages` counts only when the root has no `app` or `pages`, as Next reads them. On the Pages Router the route is an API route — a file of the pages folder at `/api` or under it — whose default export is `createPagesReleaseHandler` or always returns its call, and the listener is `<MapledLive />` from `@mapled/next/live/pages` in `pages/_app`: a listener without it gets the API route to add (`pages/api/mapled/release.ts` by default; an endpoint outside `/api` no API route can answer). ⚠ there too when the API route may run on the edge runtime — `runtime` or `config.runtime` other than `"nodejs"`, or written where doctor can't read it (Next reads both only as literals) — where the handler has no Node request and response; when a listener the App Router may run asks it — a file of `app/`, or on a site with both folders one either router may render: the API route answers Mapled's live release, which moves before the webhook refreshes what App Router pages read; and when `<MapledLive />` from `@mapled/next/live/pages` sits in the App Router's folder, where it can't mount. doctor reads the files, not how Next serves them at run time: rewrites and what a middleware does on the path aren't checked, and neither is whether a page renders the component that listens; `revalidate` on the route is no ⚠ — the handler's read names its own. The Mapled side, from the same status the AI agent's `check_integration` tool reads: whether the site has read content with the delivery key, the publish webhook and its last delivery, the preview route on the deployed site, the bindings health.
+The repository side: the link, the sign-in, the generated types, the schema pin, the site manifest (and whether it matches what was pushed), the integration hash — one line saying whether the pin and the manifest here describe the same integration Mapled holds, and if not, what moved (the schema, the bindings, or edits made in Mapled) and which command catches up — `MAPLED.md` (and whether it is what Mapled would render now), `MAPLED_KEY` and `MAPLED_WEBHOOK_SECRET` in your env files (names only — values are never read out), env files or Mapled secrets tracked by git, the installed `@mapled/next` and CLI versions, the revalidation and preview routes of a Next.js site, and its live updates — ○ «Not used» while no page mounts `<MapledLive />` or calls `watchRelease`, ✓ when the route they ask answers its `GET` with `createReleaseHandler` (`GET` is the handler, or always returns its call: every return is that call, the last statement is one, and nothing throws), ⚠ when it is missing (the tabs would poll a 404) with the file to add, when the route's `GET` isn't seen to answer with the handler (exported as `POST` they would get a 405; a `GET` that only mentions it, calls it and returns something else, or answers something else on another branch, answers without the release), or when no route can be checked against the endpoint — it is relative to the page, a full address (the tab asks it as written, and doctor can't tell it's the site's own), computed, or comes from spread props; a path from the site's root is checked against the route the App Router picks for it, dynamic and catch-all folders included, among route files with the site's page extensions (`pageExtensions` in next.config; `tsx`, `ts`, `jsx`, `js` by default) and under its `basePath`; ⚠ too when a page of either router, more specific than the route, takes that path first, when the dynamic route that answers sets `dynamicParams`, when the route may set `dynamic` to anything but `"auto"` or `"force-dynamic"` (a copy Next builds without the tab's request), sets `"force-dynamic"` while `createReleaseHandler` there isn't seen to keep a `revalidate` above 0 (its default does; with `false` or `0` Next reads the release past the cache tag) or `fetchCache` to anything but `"auto"` (the release read past the cache tag, before the webhook refreshes the pages), when next.config sets `output: "export"` (no server runs the route), or when next.config may set `pageExtensions`, `basePath` or `output` where doctor can't read them — it reads them only as literals, once, in the object the file exports, and only while the file is declarative: type imports, declarations of data, one export of the config object itself, and functions only as Next's hooks (`webpack`, `headers` …) in it. A module the file loads (a plugin such as `withMDX`, a `path` helper, an env check), a config exported as a function, any other code, a spread or a getter leaves the config unread. With a `basePath`, a listener that gives no endpoint asks under it from `@mapled/next` 0.10.0 — doctor reads the version the site has installed, and it's a ⚠ when that is older or missing. A `middleware` file (`proxy` in Next 16) next to the folder Next reads is a ⚠ unless its matcher, read the way Next's build reads `export const config`, surely leaves the route's path alone: it has no matcher, doctor can't read it, a source may take the path, or next.config has locales (`i18n`). `src/app` or `src/pages` counts only when the root has no `app` or `pages`, as Next reads them. On the Pages Router the route is an API route — a file of the pages folder at `/api` or under it — whose default export is `createPagesReleaseHandler` or always returns its call, and the listener is `<MapledLive />` from `@mapled/next/live/pages` in `pages/_app`: a listener without it gets the API route to add (`pages/api/mapled/release.ts` by default; an endpoint outside `/api` no API route can answer). ⚠ there too when the API route may run on the edge runtime — `runtime` or `config.runtime` other than `"nodejs"`, or written where doctor can't read it (Next reads both only as literals) — where the handler has no Node request and response; when a listener the App Router may run asks it — a file of `app/`, or on a site with both folders one either router may render: the API route answers Mapled's live release, which moves before the webhook refreshes what App Router pages read; and when `<MapledLive />` from `@mapled/next/live/pages` sits in the App Router's folder, where it can't mount. doctor reads the files, not how Next serves them at run time: rewrites and what a middleware does on the path aren't checked, and neither is whether a page renders the component that listens; `revalidate` on the route is no ⚠ — the handler's read names its own. The Mapled side, from the same status the AI agent's `check_integration` tool reads: whether the site has read content with the delivery key (for a project with a staging channel, through which key: production's or staging's — the key decides which releases a deployment shows), the publish webhook and its last delivery, the preview route on the deployed site, the bindings health.
 
 A site rendered in the visitor's browser — a React single-page app (Vite and the like), plain HTML — is checked for what it has: the package line is `@mapled/react`, Environment wants `VITE_MAPLED_KEY` and no webhook secret, and the routes and the webhook read ○ «Not needed» — such a site shows a publish on its next load and trades Mapled's preview link on the page itself; Live updates reads ○ as well: `live` on `MapledProvider` or `data-mapled-live` asks Mapled directly, with no route of the site's. Plain HTML installs nothing: the line is `@mapled/vanilla`, read from the script tag in the pages (or from a copy of the file next to them) — ⚠ when the address has no version or an older one, and before that when a page's tag has an `integrity` a browser won't pass: from another origin without `crossorigin` (a browser checks only a file that came with CORS), `crossorigin="use-credentials"` on jsDelivr or unpkg (their `*` answer fails a request with credentials, integrity or not), or a digest that isn't the file's — for a copy next to the pages, the copy's own; for a jsDelivr or unpkg address, the released file's of the version in it (another host may serve a file of its own; an address with a query isn't checked — `?meta` answers with something else), which doctor knows without the network for the releases up to its own, or from `node_modules/@mapled/vanilla` of that version — and Generated types and Environment read ○: the fields are named in attributes, the delivery key sits in the page. doctor takes the framework from `mapled.json`, or works it out from `package.json` (no `package.json` and an `index.html` is plain HTML). Whatever the framework, a server key or a signing secret under a public prefix (`VITE_…`, `NEXT_PUBLIC_…`) is a ✗: it would ship to every visitor.
 

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,12 +732,12 @@ 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) {
-        checks.push(dr.checkReads(status.delivery.lastReadAt));
+        checks.push(dr.checkReads(status.delivery.lastReadAt, status.delivery.staging));
         checks.push(dr.checkWebhook(status.webhook, { local: browser, remote: status.site }));
         let origin = null;
         try {

package/dist/doctor.d.ts

@@ -29,8 +29,12 @@ export type IntegrationStatus = {
         name: string;
         createdAt: string | null;
     };
+    /** `staging` only for a project with a staging delivery key (release channels). */
     delivery: {
         lastReadAt: string | null;
+        staging?: {
+            lastReadAt: string | null;
+        };
     };
     webhook: {
         url: string | null;
@@ -101,6 +105,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 +162,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 +184,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;
@@ -190,7 +214,13 @@ export declare function checkRoute(kind: RouteKind, found: RouteFile | null, fra
     code listens, whether a route answers it. `facts` is null when the
     code wasn't read (a stack this check doesn't cover). */
 export declare function checkLive(facts: LiveFacts | null, framework: string | undefined): Check;
-export declare function checkReads(lastReadAt: string | null): Check;
+/** The delivery key decides which release channel a site reads: a
+    project with a staging key has two, and the line says which of them
+    sites read through — a production site on the staging key shows
+    releases nobody promoted. */
+export declare function checkReads(lastReadAt: string | null, staging?: {
+    lastReadAt: string | null;
+}): Check;
 export declare function checkWebhook(webhook: IntegrationStatus["webhook"], site?: {
     local: boolean;
     remote: IntegrationStatus["site"];

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 };
 }
@@ -882,9 +991,14 @@ export function checkLive(facts, framework) {
         }
     }
 }
-export function checkReads(lastReadAt) {
+/** The delivery key decides which release channel a site reads: a
+    project with a staging key has two, and the line says which of them
+    sites read through — a production site on the staging key shows
+    releases nobody promoted. */
+export function checkReads(lastReadAt, staging) {
     const label = "Site reads content";
-    if (!lastReadAt) {
+    const viaStaging = staging?.lastReadAt ?? null;
+    if (!lastReadAt && !viaStaging) {
         return {
             key: "reads",
             label,
@@ -892,7 +1006,22 @@ export function checkReads(lastReadAt) {
             detail: "No reads yet. Deploy the site and open a page that shows Mapled content.",
         };
     }
-    return { key: "reads", label, status: "passed", detail: `Last read ${ago(lastReadAt)}` };
+    if (!staging)
+        return { key: "reads", label, status: "passed", detail: `Last read ${ago(lastReadAt)}` };
+    if (!lastReadAt) {
+        return {
+            key: "reads",
+            label,
+            status: "passed",
+            detail: `Staging key: last read ${ago(viaStaging)}. No reads with the production key yet — a site on the staging key shows staging releases.`,
+        };
+    }
+    return {
+        key: "reads",
+        label,
+        status: "passed",
+        detail: `Production key: last read ${ago(lastReadAt)}. Staging key: ${viaStaging ? `last read ${ago(viaStaging)}` : "no reads yet"}.`,
+    };
 }
 export function checkWebhook(webhook, site) {
     const label = "Publish webhook";

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.5",
   "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",