@mapled/cli 0.14.2 → 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";
@@ -130,6 +130,8 @@ Scanned 2 HTML files — 2 pages, 11 bindings.
 
 For a Next.js site the scan also records its live updates: `capabilities.realtime` is `true`, with the route in `releaseRoute`, when `<MapledLive />` or `watchRelease` asks — at the default path or one written in the code — a route whose exported `GET` answers with `createReleaseHandler`, or, on the Pages Router, an API route whose default export answers with `createPagesReleaseHandler` (with `<MapledLive />` from `@mapled/next/live/pages` in `pages/_app`), and `false` otherwise — `MAPLED.md` then tells the next agent whether open tabs follow Publish. Capabilities aren't part of the integration hash; `doctor`'s Site manifest line says when the pushed ones differ.
 
+On a site with more than one language the scan records how the routes carry it: `locales` is `{ "routing": "prefix", "param": "locale" }` when the routes start with a segment named for the language (`/[locale]/blog/[slug]`) — Mapled then builds each language's address of a record from it (the editor's routes, Preview), a translated slug being the address in that language. Write `{ "routing": "prefix-except-default" }` by hand when the default language lives at the root and the others under `/ru/…`, `/de/…` (without `param` Mapled puts the language before the page); leave `locales` out when every language shares one address. It is part of the integration hash.
+
 `--write` creates or updates `mapled/manifest.json`. Bindings the scan can't see (written by your AI agent, or by hand) are kept and listed; `--prune` drops them. Commit the file.
 
 ## Validate and push the manifest
@@ -140,7 +142,7 @@ npx @mapled/cli bindings push
 npx @mapled/cli bindings pull
 ```
 
-`manifest validate` checks `mapled/manifest.json` the way Mapled will: the shape and limits, duplicate keys, and — against the schema pin or the live schema — collections and fields that don't exist and targets that don't fit the field type, plus files the repository doesn't have. Problems exit 1; warnings only tell you what Mapled would grade down.
+`manifest validate` checks `mapled/manifest.json` the way Mapled will: the shape and limits, duplicate keys, `capabilities` and `locales` (`routing` and `param` only, as Mapled's schema takes them — and whether a page route has the `param` segment), and — against the schema pin or the live schema — collections and fields that don't exist and targets that don't fit the field type, plus files the repository doesn't have. Problems exit 1; warnings only tell you what Mapled would grade down.
 
 `bindings push` sends the manifest to Mapled (the same call your AI agent's `push_site_manifest` makes). Mapled grades every binding — healthy, type mismatch, outdated, missing on site — and the result shows up in **Structure → Bindings**. The push also records the integration hash: one marker over the schema and these bindings, what the site is synced with from now on. `--dry-run` validates and stops. Pushing bindings changes structure, so it needs the builder plan.
 
@@ -254,9 +256,10 @@ Still hardcoded
 ```bash
 npx @mapled/cli preview
 npx @mapled/cli preview articles hello-world
+npx @mapled/cli preview articles hello-world --locale ru
 ```
 
-Prints a Preview link — the one the **Preview** button in Mapled opens: the site in draft mode, with every saved change that isn't published yet. Name a collection and a record's slug (or id) and the link lands on the record's page, the one the pushed site manifest says shows it; a collection alone opens the page that lists it, a single its page, nothing at all the home page. Mapled makes the link after checking that the site answers and mounts its preview route; it works once, for five minutes. A plain HTML site whose pages are built with the content in them has no page for a record it wasn't built with: for such a record the command says so instead of printing a link — its page appears once the site is built with it. `--open` opens it in your browser instead of printing it; `--json` prints the link with the page and when it expires.
+Prints a Preview link — the one the **Preview** button in Mapled opens: the site in draft mode, with every saved change that isn't published yet. Name a collection and a record's slug (or id) and the link lands on the record's page, the one the pushed site manifest says shows it; a collection alone opens the page that lists it, a single its page, nothing at all the home page. Mapled makes the link after checking that the site answers and mounts its preview route; it works once, for five minutes. A plain HTML site whose pages are built with the content in them has no page for a record it wasn't built with: for such a record the command says so instead of printing a link — its page appears once the site is built with it. `--locale <code>` opens the page in that language — the address Mapled builds from the manifest's `locales` (a translated slug is the address in its language); a language the project doesn't have is refused. `--open` opens it in your browser instead of printing it; `--json` prints the link with the page, the language when one was asked, and when it expires.
 
 ## Options
 

package/dist/args.js

@@ -2,7 +2,7 @@ import { CliError } from "./errors.js";
 /** Minimal argument parsing: the leading words name the command;
     `--flag`, `--flag=value` and `--flag value` (for the flags that take
     one) follow. Nothing here is user content beyond the command line. */
-const VALUE_FLAGS = new Set(["api", "project", "out", "key"]);
+const VALUE_FLAGS = new Set(["api", "project", "out", "key", "locale"]);
 export function parseArgs(argv) {
     const words = [];
     const flags = {};

package/dist/commands.d.ts

@@ -38,10 +38,12 @@ export declare function formsList(ctx: Ctx, flags: Flags): Promise<void>;
     applied setup run (S-42) and what the agent reported; `--verify` runs
     the server checks again first, as "Run checks again" does. */
 export declare function integrationReport(ctx: Ctx, flags: Flags): Promise<number>;
-/** `mapled preview [<collection> [<slug>]]` — a Preview link from Mapled's
-    launcher, the one the Preview button opens: the token is Mapled's, the
-    CLI only passes it on. `--open` hands it to the browser instead of
-    printing it (the link works once). */
+/** `mapled preview [<collection> [<slug>]] [--locale <code>]` — a Preview
+    link from Mapled's launcher, the one the Preview button opens: the token
+    is Mapled's, the CLI only passes it on. `--locale` opens the page in that
+    language (§28.4: Mapled builds the address from the manifest's `locales`;
+    a language the project doesn't have is refused by Mapled). `--open` hands
+    it to the browser instead of printing it (the link works once). */
 export declare function preview(ctx: Ctx, flags: Flags, words: string[]): Promise<void>;
 export declare function scan(ctx: Ctx, flags: Flags): Promise<void>;
 export declare function doctor(ctx: Ctx, flags: Flags): Promise<number>;

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));
     }
@@ -360,7 +360,7 @@ export async function bindingsPull(ctx, flags) {
     if (local && !flags.force) {
         const diff = compareManifests(local.manifest, stored.manifest);
         // capabilities a scan just recorded are as much the repository's as its bindings
-        if (!diff.same || diff.capabilitiesDiffer) {
+        if (!diff.same || diff.capabilitiesDiffer || diff.localesDiffer) {
             const parts = [];
             if (diff.onlyLocal.length > 0)
                 parts.push(`${diff.onlyLocal.length} not pushed`);
@@ -370,6 +370,8 @@ export async function bindingsPull(ctx, flags) {
                 parts.push(`${diff.onlyRemote.length} only in Mapled`);
             if (diff.capabilitiesDiffer)
                 parts.push("capabilities changed");
+            if (diff.localesDiffer)
+                parts.push("routes by language changed");
             throw new CliError(`${MANIFEST_FILE} differs from the pushed manifest (v${stored.version}): ${parts.join(", ")}. Pass --force to overwrite it, or push yours with \`mapled bindings push\`.`);
         }
     }
@@ -478,21 +480,28 @@ export async function integrationReport(ctx, flags) {
             ctx.out(line);
     return report.checks.some((c) => c.status === "failed") ? 1 : 0;
 }
-/** `mapled preview [<collection> [<slug>]]` — a Preview link from Mapled's
-    launcher, the one the Preview button opens: the token is Mapled's, the
-    CLI only passes it on. `--open` hands it to the browser instead of
-    printing it (the link works once). */
+/** `mapled preview [<collection> [<slug>]] [--locale <code>]` — a Preview
+    link from Mapled's launcher, the one the Preview button opens: the token
+    is Mapled's, the CLI only passes it on. `--locale` opens the page in that
+    language (§28.4: Mapled builds the address from the manifest's `locales`;
+    a language the project doesn't have is refused by Mapled). `--open` hands
+    it to the browser instead of printing it (the link works once). */
 export async function preview(ctx, flags, words) {
     const [collection, record, ...rest] = words;
     if (rest.length > 0) {
         throw new CliError("Name a collection and, optionally, one record's slug: `mapled preview articles hello-world`.", 2);
     }
+    const locale = stringFlag(flags, "locale");
+    if (locale !== undefined && !/^[A-Za-z0-9_-]{1,40}$/.test(locale)) {
+        throw new CliError("--locale takes a language code such as ru or pt-BR.", 2);
+    }
     const { session } = await openSession(ctx, flags);
     let answer;
     try {
         answer = await session.send("POST", "/v1/agent/preview", {
             ...(collection ? { collection } : {}),
             ...(record ? { record } : {}),
+            ...(locale ? { locale } : {}),
         });
     }
     catch (err) {
@@ -516,11 +525,13 @@ export async function preview(ctx, flags, words) {
     if (typeof answer.url !== "string" || !/^https?:\/\/[!-~]+$/.test(answer.url)) {
         throw new CliError("Mapled answered with a link this CLI can't print. Update @mapled/cli and try again.");
     }
+    // the language Mapled opened the page in (the answer names it only when one was asked)
+    const inLanguage = typeof answer.locale === "string" && /^[A-Za-z0-9_-]{1,40}$/.test(answer.locale) ? answer.locale : null;
     if (flags.json) {
-        ctx.out(JSON.stringify({ url: answer.url, path: answer.path, expiresAt: answer.expiresAt ?? null }, null, 2));
+        ctx.out(JSON.stringify({ url: answer.url, path: answer.path, expiresAt: answer.expiresAt ?? null, ...(inLanguage ? { locale: inLanguage } : {}) }, null, 2));
         return;
     }
-    const where = answer.path ? clean(answer.path, 500) : "the site's home page";
+    const where = (answer.path ? clean(answer.path, 500) : "the site's home page") + (inLanguage ? ` in ${inLanguage}` : "");
     const lifetime = linkLifetime(answer.expiresAt);
     const project = clean(session.conn.projectName, 120);
     if (flags.open && (await ctx.openBrowser(answer.url))) {
@@ -626,6 +637,8 @@ export async function scan(ctx, flags) {
             parts.push(`${merged.unchanged.length} unchanged`);
         if (merged.capabilitiesChanged)
             parts.push("capabilities updated");
+        if (merged.localesChanged)
+            parts.push("routes by language updated");
         ctx.out(`Wrote ${MANIFEST_FILE} — ${manifestSummary(merged.manifest)}${parts.length > 0 && existing ? ` (${parts.join(", ")})` : ""}.${keptNote}${droppedNote}`);
         ctx.out("Next: `mapled bindings push`.");
     }
@@ -641,10 +654,12 @@ export async function scan(ctx, flags) {
         parts.push(`${merged.unchanged.length} unchanged`);
         if (merged.capabilitiesChanged)
             parts.push("capabilities changed");
+        if (merged.localesChanged)
+            parts.push("routes by language changed");
         if (merged.kept.length > 0)
             parts.push(`${merged.kept.length} not found in the code (${merged.kept.slice(0, 5).join(", ")}${merged.kept.length > 5 ? ", …" : ""})`);
         ctx.out(`Compared with ${MANIFEST_FILE}: ${parts.join(", ")}.`);
-        if (merged.added.length > 0 || merged.changed.length > 0 || merged.capabilitiesChanged) {
+        if (merged.added.length > 0 || merged.changed.length > 0 || merged.capabilitiesChanged || merged.localesChanged) {
             ctx.out(`Run \`mapled scan --write\` to update ${MANIFEST_FILE}, then \`mapled bindings push\`.`);
         }
         else {
@@ -715,10 +730,12 @@ export async function doctor(ctx, flags) {
     // plain HTML installs nothing: the runtime comes with a script tag
     checks.push(framework === "plain-html" ? dr.checkScriptTag(await dr.findScriptTag(dir, status?.site?.url), status?.sdk[sdk]) : dr.checkSdk(await dr.installedVersion(dir, sdk), status?.sdk[sdk], sdk));
     checks.push(dr.checkCli(ctx.version, status?.sdk["@mapled/cli"]));
-    checks.push(dr.checkRoute("revalidate", await dr.findRoute(dir, "revalidate"), framework));
-    checks.push(dr.checkRoute("preview", await dr.findRoute(dir, "preview"), framework));
+    // 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), 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(!framework || framework === "nextjs" ? await findLive(dir) : null, framework));
+    checks.push(dr.checkLive(live, framework));
     if (status) {
         checks.push(dr.checkReads(status.delivery.lastReadAt));
         checks.push(dr.checkWebhook(status.webhook, { local: browser, remote: status.site }));

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,12 +158,29 @@ 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 = {
     file: string;
     usesAdapter: boolean;
+    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;
@@ -180,7 +203,9 @@ export declare function checkEnv(names: Map<string, string>, env: NodeJS.Process
 export declare function checkSecrets(facts: GitFacts): Check;
 export declare function checkSdk(pkg: PackageVersion, latest: string | undefined, name?: string): Check;
 export declare function checkCli(current: string, latest: string | undefined): Check;
-export declare function checkRoute(kind: RouteKind, found: RouteFile | null, framework: string | undefined): Check;
+/** `listens`: a page follows Publish (<MapledLive /> or watchRelease) — then
+    the revalidate route's answer is what the release route trusts (#435). */
+export declare function checkRoute(kind: RouteKind, found: RouteFile | null, framework: string | undefined, listens?: boolean): Check;
 /** Live updates (§18.8): whether open tabs follow Publish, and when the
     code listens, whether a route answers it. `facts` is null when the
     code wasn't read (a stack this check doesn't cover). */

package/dist/doctor.js

@@ -5,7 +5,7 @@ import path from "node:path";
 import { promisify } from "node:util";
 import { parseDocument } from "./html5.js";
 import { integrationHash } from "./integrationHash.js";
-import { BASE_PATH_SINCE, fullAddress, liveState, pagesRouteFileFor, RELEASE_ROUTE, routeFileFor, runsIn } from "./live.js";
+import { BASE_PATH_SINCE, fullAddress, liveState, pagesRouteFileFor, RELEASE_ROUTE, revalidateRouteFacts, routeFileFor, runsIn } from "./live.js";
 import { compareManifests, manifestSummary, MANIFEST_FILE } from "./manifest.js";
 import { SCHEMA_FILE } from "./pin.js";
 import { htmlPage } from "./scanHtml.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;
@@ -468,10 +576,11 @@ export async function findRoute(dir, kind) {
             catch {
                 continue;
             }
-            return { file: rel, usesAdapter: text.includes(ROUTE_HANDLER[kind]) };
+            const usesAdapter = text.includes(ROUTE_HANDLER[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) {
@@ -639,7 +748,9 @@ export function checkCli(current, latest) {
     }
     return { key: "cli", label, status: "passed", detail: latest ? `${current} (current)` : current };
 }
-export function checkRoute(kind, found, framework) {
+/** `listens`: a page follows Publish (<MapledLive /> or watchRelease) — then
+    the revalidate route's answer is what the release route trusts (#435). */
+export function checkRoute(kind, found, framework, listens = false) {
     const key = `route_${kind}`;
     const label = kind === "revalidate" ? "Revalidation route" : "Preview route";
     const handler = ROUTE_HANDLER[kind];
@@ -653,26 +764,43 @@ export function checkRoute(kind, found, framework) {
                 : "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) {
+        return {
+            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 ${adapter.server}, or answer with the header x-mapled-cache: await cacheMark().`,
+        };
+    }
+    if (kind === "revalidate" && listens && found.fetchCache) {
+        return {
+            key,
+            label,
+            status: "warning",
+            detail: `${found.file} may set fetchCache to something other than "auto" — with "force-no-store" every answer names a new cache mark, so the release route may name no release and open tabs don't follow Publish. Leave fetchCache out of the route.`,
+        };
+    }
     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 };
 }
@@ -1021,7 +1149,7 @@ export function checkManifestFile(local, remote) {
     if (remote === null)
         return { key: "manifest", label, status: "warning", detail: `${MANIFEST_FILE} isn't pushed yet — run \`mapled bindings push\`.` };
     const diff = compareManifests(local.manifest, remote.manifest);
-    if (diff.same && !diff.capabilitiesDiffer) {
+    if (diff.same && !diff.capabilitiesDiffer && !diff.localesDiffer) {
         return { key: "manifest", label, status: "passed", detail: `${MANIFEST_FILE} is pushed as manifest v${remote.version} (${manifestSummary(local.manifest)})` };
     }
     const parts = [];
@@ -1034,6 +1162,8 @@ export function checkManifestFile(local, remote) {
     // capabilities aren't in the integration hash, so this is the line that notices them
     if (diff.capabilitiesDiffer)
         parts.push("capabilities changed");
+    if (diff.localesDiffer)
+        parts.push("routes by language changed");
     return {
         key: "manifest",
         label,

package/dist/index.js

@@ -28,7 +28,7 @@ Usage
   mapled forms list [--json]                          List the project's forms and where the site posts to
   mapled doctor [--json]                              Check the integration end to end
   mapled integration report [--json] [--verify]       Show the last setup run's verification checklist and report
-  mapled preview [<collection> [<slug>]] [--open]     Print a one-time Preview link that shows the drafts on the site
+  mapled preview [<collection> [<slug>]] [--locale <code>] [--open]   Print a one-time Preview link that shows the drafts on the site
 
 Options
   --version, -v   Print the version

package/dist/integrationHash.d.ts

@@ -1,7 +1,7 @@
 /** The integration hash (§21.4): one marker over everything the site's
     integration was written against — the schema (its hash, the twelve hex
     characters in mapled-types.ts and mapled/schema.json) and the site
-    manifest (bindings, pages, framework, notes). Mapled records it on
+    manifest (bindings, pages, framework, notes, routes by language). Mapled records it on
     every manifest push and computes it again on read; the repository
     computes the same value from mapled/schema.json and
     mapled/manifest.json, and `mapled doctor` compares the two in one
@@ -31,5 +31,10 @@ export type HashedManifest = {
     }[] | null;
     bindings: HashedBinding[];
     notes?: string[] | null;
+    /** routes by language (§28.4); a manifest without it hashes as before */
+    locales?: {
+        routing: string;
+        param?: string | null;
+    } | null;
 };
 export declare function integrationHash(schemaHash: string, manifest: HashedManifest): string;

package/dist/integrationHash.js

@@ -21,6 +21,8 @@ export function integrationHash(schemaHash, manifest) {
         }))
             .sort((a, b) => byText(a.key, b.key)),
         notes: manifest.notes ?? [],
+        // only when declared: the hashes of every manifest without it stay what they were
+        ...(manifest.locales ? { locales: { routing: manifest.locales.routing, param: manifest.locales.param || null } } : {}),
     };
     return createHash("sha256").update(JSON.stringify(projection)).digest("hex").slice(0, 12);
 }

package/dist/live.d.ts

@@ -208,6 +208,16 @@ export declare function liveInFile(file: string, text: string, router?: "app" |
     segment?: SegmentSetting;
     runtime?: string | null;
 };
+/** What the revalidate (webhook) route does that live updates depend on
+    (§18.8, #435): whether it answers with the cache's mark (`cacheMark()`,
+    which createRevalidateHandler does for you), and whether it may export
+    `fetchCache` as anything but "auto" — "force-no-store" makes every
+    answer name a new mark, so the release route may name no release.
+    Read the way the release route's segment config is read. */
+export declare function revalidateRouteFacts(text: string): {
+    cacheMark: boolean;
+    fetchCache: boolean;
+};
 /** The route segment settings that change how Next serves the release
     route or reads what the handler reads, in the order doctor names them:
     `dynamic` can make it a static copy built without the tab's request,

package/dist/live.js

@@ -945,6 +945,19 @@ export function liveInFile(file, text, router = "app") {
     const segment = sets("dynamic", SEGMENT_KEEPS.dynamic) ? "dynamic" : forced() ? "force-dynamic" : sets("fetchCache", SEGMENT_KEEPS.fetchCache) ? "fetchCache" : undefined;
     return { listeners, handler: releaseHandlerOf(tokens, APP_HANDLER(names), "GET", read), params, ...(segment ? { segment } : {}) };
 }
+/** What the revalidate (webhook) route does that live updates depend on
+    (§18.8, #435): whether it answers with the cache's mark (`cacheMark()`,
+    which createRevalidateHandler does for you), and whether it may export
+    `fetchCache` as anything but "auto" — "force-no-store" makes every
+    answer name a new mark, so the release route may name no release.
+    Read the way the release route's segment config is read. */
+export function revalidateRouteFacts(text) {
+    const tokens = tokenize(text);
+    const cacheMark = tokens.some((t, k) => t.kind === "ident" && t.value === "cacheMark" && isPunct(tokens[k + 1], "("));
+    const listing = tokens.some((u, k) => isWord(u, "exports") || (isWord(u, "export") && isPunct(tokens[k + 1], "*")));
+    const fetchCache = (listing || tokens.some((u) => isName(u, "fetchCache"))) && setsExport(tokens, readingOf(tokens).b.after, "fetchCache", SEGMENT_KEEPS.fetchCache);
+    return { cacheMark, fetchCache };
+}
 /** Whether every release handler the file makes keeps a window of its own
     for the pointer's read (keepsWindow), with the factory only ever called
     where it's named: `const make = createReleaseHandler`, a namespace

package/dist/manifest.d.ts

@@ -30,6 +30,18 @@ export type ManifestCapabilities = {
     realtime?: boolean;
     releaseRoute?: string;
 };
+/** How the site's routes carry the language (§28.4): `prefix` — every
+    language under its own (`/en/…`, `/ru/…`), `prefix-except-default` —
+    the default language at the root, the others under theirs; `param`
+    names the dynamic segment that holds it (`/[locale]/blog/[slug]`),
+    without one Mapled puts the language before the page. Part of the
+    integration hash: Mapled builds each language's address of a record
+    from it (the editor's routes, Preview). */
+export type ManifestLocales = {
+    routing: "prefix" | "prefix-except-default";
+    param?: string;
+};
+export declare const LOCALE_ROUTINGS: readonly ["prefix", "prefix-except-default"];
 export type Manifest = {
     framework?: string;
     integrationMode?: string;
@@ -37,6 +49,7 @@ export type Manifest = {
     bindings: ManifestBinding[];
     notes?: string[];
     capabilities?: ManifestCapabilities;
+    locales?: ManifestLocales;
 };
 export declare const KEY_PATTERN: RegExp;
 export declare const LIMITS: {
@@ -93,6 +106,8 @@ export declare function readManifestFile(dir: string): Promise<{
     the order they came in. */
 export declare function writeManifestFile(dir: string, manifest: Manifest): Promise<string>;
 export declare function orderManifest(manifest: Manifest): Manifest;
+/** Whether two manifests route languages the same way (missing on both is the same). */
+export declare function sameLocales(a: ManifestLocales | undefined, b: ManifestLocales | undefined): boolean;
 /** Whether two manifests declare the same capabilities (missing and empty are the same). */
 export declare function sameCapabilities(a: ManifestCapabilities | undefined, b: ManifestCapabilities | undefined): boolean;
 export declare function orderBinding(b: ManifestBinding): ManifestBinding;
@@ -100,12 +115,14 @@ export declare function plural(n: number, word: string, pluralWord?: string): st
 export declare function manifestSummary(manifest: Manifest): string;
 /** Bindings that mean the same thing to Mapled (what a push stores). */
 export declare function sameBinding(a: ManifestBinding, b: ManifestBinding): boolean;
-/** `same` is about the bindings; `capabilitiesDiffer` says whether the capabilities do. */
+/** `same` is about the bindings; `capabilitiesDiffer` says whether the
+    capabilities do, `localesDiffer` whether the routes by language do. */
 export type ManifestComparison = {
     same: boolean;
     onlyLocal: string[];
     onlyRemote: string[];
     changed: string[];
     capabilitiesDiffer: boolean;
+    localesDiffer: boolean;
 };
 export declare function compareManifests(local: Manifest, remote: Manifest): ManifestComparison;