@mapled/cli 0.14.1 → 0.14.3

package/README.md

@@ -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. `--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

@@ -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) {
@@ -507,15 +516,22 @@ export async function preview(ctx, flags, words) {
     if (answer.status === "not_set_up") {
         throw new CliError(`${clean(answer.origin)} has no preview route — mount createPreviewHandler from "@mapled/next/server" at /api/mapled/preview and redeploy.`);
     }
+    if (answer.status === "no_route") {
+        // a site with its content baked in at build time has no page for a record it wasn't built with (§22.7 п. 3)
+        const where = answer.path ? `at ${clean(answer.path, 500)}` : "for this record";
+        throw new CliError(`${clean(answer.origin)} has no page ${where} — if the record is new, its page appears once the site is built with it. Then try again.`);
+    }
     // the link is printed as it came (masking would drop the token): printable ASCII only
     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))) {
@@ -621,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`.");
     }
@@ -636,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 {
@@ -710,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));
+    // 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));
     // 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

@@ -153,9 +153,12 @@ export declare function detectFramework(dir: string): Promise<string | undefined
 export declare function compareVersions(a: string, b: string): number;
 export type RouteKind = "revalidate" | "preview";
 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>;
 /** GET the site's preview route without a token — the adapter answers 400. */
@@ -180,7 +183,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";
@@ -468,7 +468,8 @@ 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;
@@ -639,7 +640,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];
@@ -671,6 +674,22 @@ export function checkRoute(kind, found, framework) {
                 detail: `app/api/mapled/preview/route.ts is missing — mount ${handler} from "@mapled/next/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 "@mapled/next/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".` };
     }
@@ -1021,7 +1040,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 +1053,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/html5.d.ts

@@ -18,11 +18,21 @@ import { type Token, type TreeAdapter, type TreeAdapterTypeMap } from "parse5";
       before a <table>: indexOf), the adoption agency (a misnested </b>:
       splice from the front) and repeated <html>/<body> tags (every
       attribute so far) walk them — 160,000 "a<br>" in a table: 11 s.
-    The worst page within the cap is the depth times its start tags. */
+    The worst page within the cap is the depth times its start tags.
+
+    parse5 can't read a numeric character reference of 309 or more decimal
+    digits, or of 256 or more hex ones, at all: BadReference. */
 /** How deep elements may be open at once — Chrome's own limit of the tree it builds. */
 export declare const MAX_OPEN = 512;
 export declare class TooDeep extends Error {
 }
+/** A numeric character reference parse5 can't read: its decoder (entities)
+    multiplies by 10 or 16 to the power of the digits — Infinity past 308
+    decimal or 255 hex ones — and 0 × Infinity is NaN, on which parse5
+    throws RangeError. Browsers read it as a character. The same guard is
+    in the preview proxy's reader (apps/api/src/lib/previewProxyHtml.ts). */
+export declare class BadReference extends Error {
+}
 export type Html5Attr = Token.Attribute;
 /** A node of the tree: an element (tagName), text, a comment, a doctype,
     the document or a template's content — children linked both ways. Its
@@ -61,6 +71,7 @@ type Map_ = TreeAdapterTypeMap<Html5Node, Html5Node, Html5Node, Html5Node, Html5
 /** parse5's default tree adapter, method for method, on linked children. */
 export declare const linked: TreeAdapter<Map_>;
 /** The document, with scripting on — as the runtime sees it (a <noscript>
-    is text). Throws TooDeep past MAX_OPEN open elements. */
+    is text). Throws TooDeep past MAX_OPEN open elements, BadReference at a
+    numeric character reference parse5 can't read. */
 export declare function parseDocument(text: string): Html5Node;
 export {};

package/dist/html5.js

@@ -7853,6 +7853,9 @@ var VOID_ELEMENTS = /* @__PURE__ */ new Set([
 var MAX_OPEN = 512;
 var TooDeep = class extends Error {
 };
+var BadReference = class extends Error {
+};
+var isCodePoint = (cp) => Number.isInteger(cp) && cp >= 0 && cp <= 1114111;
 var Html5Node = class {
   constructor(nodeName, extra = {}) {
     this.nodeName = nodeName;
@@ -7991,6 +7994,11 @@ var Guarded = class extends Parser {
       names.add(this.currentAttr.name);
       tag.attrs.push(this.currentAttr);
     };
+    const reference = tokenizer._flushCodePointConsumedAsCharacterReference;
+    tokenizer._flushCodePointConsumedAsCharacterReference = function(cp) {
+      if (!isCodePoint(cp)) throw new BadReference();
+      reference.call(this, cp);
+    };
   }
   onItemPush(...args) {
     if (this.openElements.stackTop >= MAX_OPEN) throw new TooDeep();
@@ -8001,6 +8009,7 @@ function parseDocument(text) {
   return Guarded.parse(text, { scriptingEnabled: true, treeAdapter: linked });
 }
 export {
+  BadReference,
   Html5Node,
   MAX_OPEN,
   TooDeep,

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;

package/dist/manifest.js

@@ -22,6 +22,7 @@ export const BINDING_TARGETS = [
     "form_field",
     "other",
 ];
+export const LOCALE_ROUTINGS = ["prefix", "prefix-except-default"];
 export const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:/\[\]-]{0,119}$/;
 export const LIMITS = { bindings: 500, pages: 200, notes: 20 };
 /** Field types a target renders without a transform — the API's table
@@ -91,7 +92,8 @@ export function typeLabel(type) {
 }
 const isObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
 const isText = (v, max, min = 1) => typeof v === "string" && v.length >= min && v.length <= max;
-const TOP_KEYS = new Set(["framework", "integrationMode", "pages", "bindings", "notes", "capabilities"]);
+const TOP_KEYS = new Set(["framework", "integrationMode", "pages", "bindings", "notes", "capabilities", "locales"]);
+const LOCALE_PARAM = /^[A-Za-z0-9_-]{1,60}$/;
 export const CAPABILITY_KEYS = ["realtime", "releaseRoute"];
 const BINDING_KEYS = new Set(["key", "page", "component", "file", "collection", "field", "target", "required"]);
 /** Parses the file's text into a manifest with only the known fields,
@@ -271,6 +273,31 @@ export function parseManifest(raw, file) {
                 manifest.capabilities = kept;
         }
     }
+    if (data.locales !== undefined) {
+        const loc = data.locales;
+        if (!isObject(loc)) {
+            error("locales", `"locales" must be an object — { routing, param }.`);
+        }
+        else {
+            let ok = true;
+            for (const key of Object.keys(loc)) {
+                if (key !== "routing" && key !== "param") {
+                    error(`locales.${key}`, `locales.${key} isn't part of the manifest — only routing and param; Mapled refuses the push.`);
+                    ok = false;
+                }
+            }
+            if (!LOCALE_ROUTINGS.includes(loc.routing)) {
+                error("locales.routing", `locales.routing must be "prefix" (every language under its own, /en/…) or "prefix-except-default" (the default language at the root).`);
+                ok = false;
+            }
+            if (loc.param !== undefined && !(typeof loc.param === "string" && LOCALE_PARAM.test(loc.param))) {
+                error("locales.param", `locales.param must name the dynamic segment that carries the language, e.g. "locale" for /[locale]/blog/[slug].`);
+                ok = false;
+            }
+            if (ok)
+                manifest.locales = { routing: loc.routing, ...(typeof loc.param === "string" ? { param: loc.param } : {}) };
+        }
+    }
     return { manifest, problems };
 }
 export function indexSchema(schema) {
@@ -302,6 +329,14 @@ export async function checkManifest(manifest, opts) {
     const warn = (p, message) => problems.push({ level: "warning", path: p, message });
     const index = opts.schema ? indexSchema(opts.schema) : null;
     const routes = new Set((manifest.pages ?? []).map((p) => p.route));
+    // routes by language (§28.4): a segment the manifest names must be on some page
+    if (manifest.locales?.param !== undefined) {
+        const marker = `[${manifest.locales.param}]`;
+        const all = [...routes, ...manifest.bindings.map((b) => b.page)];
+        if (all.length > 0 && !all.some((r) => r.split("?")[0].split("/").includes(marker))) {
+            warn("locales.param", `locales.param names "${marker}", but no page route has that segment — the language then goes nowhere; leave param out for Mapled to put the language before the page.`);
+        }
+    }
     for (const [i, p] of (manifest.pages ?? []).entries()) {
         if (p.file && !(await opts.fileExists(p.file))) {
             warn(`pages[${i}].file`, `pages[${i}] (${p.route}): ${p.file} doesn't exist in the repository.`);
@@ -381,8 +416,13 @@ export function orderManifest(manifest) {
         bindings: manifest.bindings.map(orderBinding),
         ...(manifest.notes && manifest.notes.length > 0 ? { notes: [...manifest.notes] } : {}),
         ...(manifest.capabilities ? { capabilities: orderCapabilities(manifest.capabilities) } : {}),
+        ...(manifest.locales ? { locales: { routing: manifest.locales.routing, ...(manifest.locales.param !== undefined ? { param: manifest.locales.param } : {}) } } : {}),
     };
 }
+/** Whether two manifests route languages the same way (missing on both is the same). */
+export function sameLocales(a, b) {
+    return (a?.routing ?? null) === (b?.routing ?? null) && (a?.param ?? null) === (b?.param ?? null);
+}
 function orderCapabilities(c) {
     return {
         ...(c.realtime !== undefined ? { realtime: c.realtime } : {}),
@@ -434,5 +474,6 @@ export function compareManifests(local, remote) {
         onlyRemote,
         changed,
         capabilitiesDiffer: !sameCapabilities(local.capabilities, remote.capabilities),
+        localesDiffer: !sameLocales(local.locales, remote.locales),
     };
 }

package/dist/report.d.ts

@@ -114,6 +114,7 @@ export type PreviewAnswer = {
     url: string;
     expiresAt?: string;
     path: string | null;
+    locale?: string;
 } | {
     status: "not_deployed";
     origin: string;
@@ -122,6 +123,10 @@ export type PreviewAnswer = {
     status: "not_set_up";
     origin: string;
     path: string | null;
+} | {
+    status: "no_route";
+    origin: string;
+    path: string | null;
 };
 /** "5 minutes" until the link stops working, or null when unknown. */
 export declare function linkLifetime(expiresAt: string | undefined, now?: number): string | null;

package/dist/scan.d.ts

@@ -1,5 +1,5 @@
 import type * as TS from "typescript";
-import { type Manifest, type ManifestBinding, type ManifestCapabilities, type ManifestPage } from "./manifest.js";
+import { type Manifest, type ManifestBinding, type ManifestCapabilities, type ManifestLocales, type ManifestPage } from "./manifest.js";
 import type { Schema } from "./schema.js";
 /** `mapled scan` (§19.5, §21.4 — the standalone scanner of wave 2): reads
     the site's source and writes down what the code reads from Mapled —
@@ -39,7 +39,14 @@ export type ScanResult = {
     notes: string[];
     /** what the code says the site can do (live updates of a Next.js site); undefined keeps the manifest's */
     capabilities?: ManifestCapabilities;
+    /** how the routes carry the language (§28.4), when a leading dynamic segment names it; undefined keeps the manifest's */
+    locales?: ManifestLocales;
 };
+/** Routes by language from the file conventions (§28.4): a dynamic segment
+    named for the language at the front of a route (`/[locale]/…`,
+    `/[lang]/…`) — every language then lives under its own prefix, and
+    the segment is the manifest's `param`. Null when no route starts so. */
+export declare function detectLocales(routes: Iterable<string>): ManifestLocales | null;
 export declare const SDK_METHODS: Set<string>;
 /** The repository's TypeScript, when it has one; the CLI ships none. */
 export declare function loadTypeScript(dir: string): TypeScriptModule | null;
@@ -90,6 +97,8 @@ export type MergeResult = {
     dropped: string[];
     /** the scan changed what an existing manifest says the site can do */
     capabilitiesChanged: boolean;
+    /** the scan changed how an existing manifest routes languages */
+    localesChanged: boolean;
 };
 /** The scan's bindings replace the ones with the same key; bindings the
     scanner can't see (an agent's, hand-written) stay unless pruned. */

package/dist/scan.js

@@ -1,7 +1,22 @@
 import { createRequire } from "node:module";
 import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
-import { sameCapabilities, targetFor } from "./manifest.js";
+import { sameCapabilities, sameLocales, targetFor } from "./manifest.js";
+/** The segment names a site gives the language at the front of its routes. */
+const LOCALE_SEGMENTS = new Set(["locale", "lang", "lng", "language"]);
+/** Routes by language from the file conventions (§28.4): a dynamic segment
+    named for the language at the front of a route (`/[locale]/…`,
+    `/[lang]/…`) — every language then lives under its own prefix, and
+    the segment is the manifest's `param`. Null when no route starts so. */
+export function detectLocales(routes) {
+    for (const route of routes) {
+        const first = route.split("/")[1];
+        const m = first ? /^\[([A-Za-z0-9_-]{1,60})\]$/.exec(first) : null;
+        if (m && LOCALE_SEGMENTS.has(m[1].toLowerCase()))
+            return { routing: "prefix", param: m[1] };
+    }
+    return null;
+}
 const SKIP_DIRS = new Set([
     "node_modules",
     ".git",
@@ -1398,6 +1413,7 @@ export async function scanRepository(dir, opts) {
     if (!opts.ts) {
         notes.push("TypeScript isn't installed in this repository, so fields weren't traced (collections only) — npm install -D typescript and scan again.");
     }
+    const locales = detectLocales(routes.pages.values());
     return {
         framework,
         parser: opts.ts ? "typescript" : "tokens",
@@ -1405,6 +1421,7 @@ export async function scanRepository(dir, opts) {
         pages: uniquePages,
         bindings: sortedBindings,
         notes,
+        ...(locales ? { locales } : {}),
     };
 }
 /** The scan's bindings replace the ones with the same key; bindings the
@@ -1451,7 +1468,10 @@ export function mergeManifest(existing, scan, opts) {
         bindings: out,
         ...(existing?.notes && existing.notes.length > 0 ? { notes: existing.notes } : {}),
         ...(scan.capabilities ? { capabilities: scan.capabilities } : existing?.capabilities ? { capabilities: existing.capabilities } : {}),
+        // the scan's routes by language, else the manifest's (written by hand or by the agent)
+        ...(scan.locales ? { locales: scan.locales } : existing?.locales ? { locales: existing.locales } : {}),
     };
     const capabilitiesChanged = existing !== null && !sameCapabilities(existing.capabilities, manifest.capabilities);
-    return { manifest, added, changed, unchanged, kept, dropped, capabilitiesChanged };
+    const localesChanged = existing !== null && !sameLocales(existing.locales, manifest.locales);
+    return { manifest, added, changed, unchanged, kept, dropped, capabilitiesChanged, localesChanged };
 }

package/dist/scanHtml.d.ts

@@ -20,7 +20,8 @@ export type HtmlElement = {
 };
 /** The elements of a page and their attributes — parse5's tree (html5.ts),
     a <template>'s children being its content. Built without recursion:
-    a page nests up to MAX_OPEN elements, deeper throws TooDeep. */
+    a page nests up to MAX_OPEN elements, deeper throws TooDeep; a
+    numeric character reference parse5 can't read throws BadReference. */
 export declare function parseHtml(text: string): HtmlElement;
 /** Where a file is served and the key its bindings start with:
     index.html → "/" (index), blog/index.html → "/blog/" (blog/index),

package/dist/scanHtml.js

@@ -1,13 +1,14 @@
 import { createHash } from "node:crypto";
 import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
-import { MAX_OPEN, parseDocument, TooDeep } from "./html5.js";
+import { BadReference, MAX_OPEN, parseDocument, TooDeep } from "./html5.js";
 import { targetFor } from "./manifest.js";
 const HTML_NS = "http://www.w3.org/1999/xhtml";
 const MAX_DEPTH = MAX_OPEN;
 /** The elements of a page and their attributes — parse5's tree (html5.ts),
     a <template>'s children being its content. Built without recursion:
-    a page nests up to MAX_OPEN elements, deeper throws TooDeep. */
+    a page nests up to MAX_OPEN elements, deeper throws TooDeep; a
+    numeric character reference parse5 can't read throws BadReference. */
 export function parseHtml(text) {
     const root = { name: "#document", attrs: new Map(), children: [] };
     const pending = [[parseDocument(text), root]];
@@ -148,6 +149,7 @@ export async function scanHtml(dir, opts) {
     const noTemplate = [];
     const unusableRoutes = [];
     const tooDeep = [];
+    const badReferences = [];
     const notGroups = [];
     const seenRoutes = new Set();
     const pageKeys = new Set();
@@ -170,9 +172,12 @@ export async function scanHtml(dir, opts) {
             doc = parseHtml(text);
         }
         catch (e) {
-            if (!(e instanceof TooDeep))
+            if (e instanceof TooDeep)
+                tooDeep.push(file);
+            else if (e instanceof BadReference)
+                badReferences.push(file);
+            else
                 throw e;
-            tooDeep.push(file);
             continue;
         }
         seenRoutes.add(served);
@@ -422,6 +427,8 @@ export async function scanHtml(dir, opts) {
         notes.push(`A list or an each without a <template> isn't filled: ${list(noTemplate)}.`);
     if (tooDeep.length > 0)
         notes.push(`Elements nest deeper than ${MAX_OPEN} levels, so the scan didn't read ${count(tooDeep) === 1 ? "this page" : "these pages"}: ${list(tooDeep)}.`);
+    if (badReferences.length > 0)
+        notes.push(`A numeric character reference (&#…;) is too long to read, so the scan didn't read ${count(badReferences) === 1 ? "this page" : "these pages"}: ${list(badReferences)}.`);
     if (unusableRoutes.length > 0)
         notes.push(`Preview can't open ${count(unusableRoutes) === 1 ? "this address" : "these addresses"} — rename the file or the slug parameter: ${list(unusableRoutes)}.`);
     // keys within the manifest's 120 characters, and still one per binding

package/dist/types.js

@@ -153,7 +153,9 @@ function renderedField(field, owner, names, extras) {
     if (field.type === "computed" && field.computed) {
         return { required: false, rendered: computedType(field.computed.resultType) };
     }
-    return { required: field.required, rendered: scalarType(field.type, field.options) };
+    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 };
 }
 /** Unique type names: the singular PascalCase of the key; the raw
     PascalCase when two keys meet there; a numeric suffix as a last resort. */

package/dist/vanillaDigests.js

@@ -8,4 +8,8 @@
 export const VANILLA_DIGESTS = {
     "0.1.0": "sha384-mbuMcQAueviAbkTzgvxc8oDtspuYH6lFLUgE+gocGexnI8ehgSgdjnNMNL7JPk4q",
     "0.1.1": "sha384-2vgQ4g9re/eiYxEa/H3WKpWI5C9L4wCB/62c8Kq+LOfZDzmqc2ozqMGC8mZoOUqk",
+    "0.1.2": "sha384-bhIJoFuEGouAZtHbYeNZeN0m6fqFVWpQw+YkSMJhfk/7m5bUwS/qVWZ3xczw/1du",
+    "0.2.0": "sha384-HJ5XG9AhAlbKe6jPRVaef3whiVup/5WhprMwqC6RwWhpq6Pb0OsRLzbLmLJ8WH0f",
+    "0.2.1": "sha384-6apTHYxXrozzwFCqNU+70Z9pa/FDnhArNomcKQNWbeKRX4scjFiOc9d7wWKCOvTU",
+    "0.2.2": "sha384-lfhwQoPUtrbLcD2HXSLr2o1z+aUAjotB62i3LFMGxzBlK5lfCQPQPLOoWL+1DBMc",
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapled/cli",
-  "version": "0.14.1",
+  "version": "0.14.3",
   "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",