@mapled/cli 0.14.0 → 0.14.2

package/README.md

@@ -206,7 +206,7 @@ Mapled doctor — Dolphin Landing
 
 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.
 
-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 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.
+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.
 
 Exit code 1 when something is marked ✗; `--json` prints the checks for scripts and agents.
 
@@ -256,7 +256,7 @@ npx @mapled/cli preview
 npx @mapled/cli preview articles hello-world
 ```
 
-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. `--open` opens it in your browser instead of printing it; `--json` prints the link with the page and when it expires.
 
 ## Options
 

package/dist/commands.js

@@ -507,6 +507,11 @@ 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.");
@@ -708,7 +713,7 @@ export async function doctor(ctx, flags) {
     checks.push(dr.checkEnv(await dr.envNames(dir), ctx.env, framework));
     checks.push(dr.checkSecrets(await dr.gitFacts(dir)));
     // plain HTML installs nothing: the runtime comes with a script tag
-    checks.push(framework === "plain-html" ? dr.checkScriptTag(await dr.findScriptTag(dir), status?.sdk[sdk]) : dr.checkSdk(await dr.installedVersion(dir, sdk), status?.sdk[sdk], sdk));
+    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));

package/dist/doctor.d.ts

@@ -110,8 +110,43 @@ export type ScriptTag = {
     file: string;
     /** null — a CDN address without a version: it follows every release */
     version: string | null;
+    /** the first page whose runtime tag a browser refuses to run */
+    refused?: Refusal;
 };
-export declare function findScriptTag(dir: string): Promise<ScriptTag | null>;
+/** Why a browser refuses the runtime's file on a page (§19.2): the tag's
+    `integrity` names a hash, and the file comes from another origin
+    without `crossorigin` — the answer is opaque, and an opaque answer
+    passes no check — or no digest of the strongest hash it names is the
+    file's — or it asks jsDelivr or unpkg with credentials
+    (`crossorigin="use-credentials"`), which they answer with a wildcard
+    a browser doesn't take for such a request. `more`: other pages with a
+    tag a browser refuses. */
+export type Refusal = {
+    file: string;
+    more: number;
+} & Why;
+type Why = {
+    cors: true;
+} | {
+    credentials: true;
+} | {
+    digest: string;
+    of: string;
+};
+export declare function findScriptTag(dir: string, site?: string | null): Promise<ScriptTag | null>;
+/** Which file's bytes an address serves, where doctor knows them without
+    the network — the one place that decides whether a digest is checked:
+    a path on the site's own origin (a file of the repository, if there is
+    one), or the published runtime of a release on an npm CDN, at its
+    canonical address (https, no port of its own). Either only when the
+    path alone decides the answer: no query (unpkg's `?meta` answers with
+    JSON, a server may answer `?v=2` with anything) and no credentials;
+    the fragment never leaves the browser. Null for anything else. */
+export declare function servedFile(src: URL, origin: string): {
+    copy: string;
+} | {
+    version: string;
+} | null;
 export declare function checkScriptTag(tag: ScriptTag | null, latest: string | undefined): Check;
 export declare function detectFramework(dir: string): Promise<string | undefined>;
 /** -1, 0 or 1 comparing dotted numeric versions; anything else compares by number. */
@@ -188,3 +223,4 @@ export declare function checkIntegration(local: {
     manifest: StoredManifest | null | "unknown";
 } | null): Check;
 export declare const REMOTE_CHECKS: [string, string][];
+export {};

package/dist/doctor.js

@@ -1,12 +1,16 @@
 import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
 import { access, readdir, readFile } from "node:fs/promises";
 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 { compareManifests, manifestSummary, MANIFEST_FILE } from "./manifest.js";
 import { SCHEMA_FILE } from "./pin.js";
+import { htmlPage } from "./scanHtml.js";
 import { splitGenerated } from "./types.js";
+import { VANILLA_DIGESTS } from "./vanillaDigests.js";
 export function ago(iso) {
     const m = Math.floor((Date.now() - new Date(iso).getTime()) / 60_000);
     if (m < 1)
@@ -111,11 +115,13 @@ export const rendersInBrowser = (framework) => framework === "react-spa" || fram
 /** 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";
 const SKIPPED_DIRS = new Set(["node_modules", ".git", ".next", ".vercel", ".netlify", "vendor"]);
-export async function findScriptTag(dir) {
+export async function findScriptTag(dir, site) {
     // pages first, breadth first, and not forever: a site's pages sit near its root
     const queue = [{ abs: dir, rel: "", depth: 0 }];
     const copies = [];
+    let pinned = null;
     let unpinned = null;
+    let refused = null;
     let seen = 0;
     while (queue.length > 0 && seen < 2000) {
         const at = queue.shift();
@@ -133,20 +139,238 @@ export async function findScriptTag(dir) {
             if (!/\.html?$/i.test(entry.name))
                 continue;
             const text = await readFile(path.join(at.abs, entry.name), "utf8").catch(() => "");
-            const pinned = /@mapled\/vanilla@(\d+\.\d+\.\d+)/.exec(text);
-            if (pinned)
-                return { file: rel, version: pinned[1] };
+            const version = /@mapled\/vanilla@(\d+\.\d+\.\d+)/.exec(text);
+            if (pinned === null && version)
+                pinned = { file: rel, version: version[1] };
             if (unpinned === null && /@mapled\/vanilla(@latest)?\//.test(text))
                 unpinned = rel;
+            // an attribute's name is in the markup as it is, ASCII case aside — its value may be written in character
+            // references: a page with neither name has nothing to refuse
+            const why = /integrity|crossorigin/i.test(text) ? await refusalOn(text, rel, dir, site) : null;
+            if (why && refused)
+                refused.more += 1;
+            else if (why)
+                refused = { file: rel, more: 0, ...why };
         }
     }
-    for (const rel of copies) {
+    let found = pinned;
+    for (const rel of found ? [] : copies) {
         const head = (await readFile(path.join(dir, rel), "utf8").catch(() => "")).slice(0, 200);
         const banner = /^\/\*! @mapled\/vanilla (\d+\.\d+\.\d+) /.exec(head);
-        if (banner)
-            return { file: rel, version: banner[1] };
+        if (banner) {
+            found = { file: rel, version: banner[1] };
+            break;
+        }
+    }
+    found ??= unpinned === null ? null : { file: unpinned, version: null };
+    return found && refused ? { ...found, refused } : found;
+}
+/** A token of `integrity` some browser may read as naming a hash — any
+    ASCII case, "sha-384" too (as the preview proxy reads it: SRI_HASH in
+    lib/previewProxy.ts of the API) — and one every browser reads alike:
+    the name as written, a digest, options after "?". */
+const SRI_HASH = /^sha-?(256|384|512)(?:[-?]|$)/i;
+const SRI_EXACT = /^sha(256|384|512)-([A-Za-z0-9+/=_-]+)(?:\?.*)?$/;
+function sriOf(value) {
+    let checked = false;
+    let alike = true;
+    let bits = 0;
+    let digests = [];
+    for (const token of value.split(/[\t\n\f\r ]+/)) {
+        if (!SRI_HASH.test(token))
+            continue;
+        checked = true;
+        const exact = SRI_EXACT.exec(token);
+        if (!exact) {
+            alike = false;
+            continue;
+        }
+        // base64url decodes too, as browsers read it
+        const digest = Buffer.from(exact[2], "base64");
+        const size = Number(exact[1]);
+        if (size > bits)
+            [bits, digests] = [size, [digest]];
+        else if (size === bits)
+            digests.push(digest);
+    }
+    return { checked, strongest: checked && alike ? { hash: `sha${bits}`, digests } : null };
+}
+const HTML_NS = "http://www.w3.org/1999/xhtml";
+/** where the pages are taken to be served when doctor doesn't know the site's address */
+const NOWHERE = "https://site.invalid";
+/** the `type` of a classic script (HTML's JavaScript MIME type essences); an empty one is classic too */
+const CLASSIC = /^(?:(?:application|text)\/(?:x-)?(?:java|ecma)script|text\/javascript1\.[0-5]|text\/(?:j|live)script)$/;
+/** The runtime's tags on a page, as a browser builds it:
+    a <script> it fetches (not in a <template>, not SVG's, a classic or a
+    module script) that names "@mapled/vanilla" or carries a delivery key.
+    The source resolves against the first <base href> before it, else the
+    page's address; a module is always fetched with CORS. A tag without
+    `integrity` reads as an empty one: nothing to check. */
+function runtimeTagsOf(text, page) {
+    const tags = [];
+    let base = null;
+    const stack = [parseDocument(text)];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        // a template's content is no part of the document: parse5 keeps it in `content`, not among the children
+        for (let child = node.lastChild; child; child = child.previousSibling)
+            stack.push(child);
+        if (node.namespaceURI !== HTML_NS)
+            continue;
+        const attr = (name) => node.attrs?.find((a) => !a.namespace && a.name === name)?.value ?? null;
+        if (node.tagName === "base" && base === null && attr("href") !== null) {
+            try {
+                base = new URL(attr("href"), page);
+                if (base.protocol === "data:" || base.protocol === "javascript:")
+                    base = page;
+            }
+            catch {
+                base = page;
+            }
+        }
+        if (node.tagName !== "script")
+            continue;
+        const src = attr("src");
+        const integrity = attr("integrity") ?? "";
+        const type = attr("type")?.trim().toLowerCase() ?? "";
+        const module = type === "module";
+        if (src === null || src.trim() === "")
+            continue;
+        if (!module && ((type !== "" && !CLASSIC.test(type)) || attr("nomodule") !== null))
+            continue;
+        if (attr("data-mapled-key") === null && !/@mapled\/vanilla[@/]/.test(src))
+            continue;
+        let url;
+        try {
+            url = new URL(src, base ?? page);
+        }
+        catch {
+            // an address a browser can't parse fetches nothing
+            continue;
+        }
+        // a data: or blob: source is no file of a server's, same origin or not
+        // any value but "use-credentials" (ASCII case aside) is the anonymous state, as is an empty one
+        const crossorigin = attr("crossorigin");
+        const cors = crossorigin === null ? (module ? "anonymous" : "none") : crossorigin.toLowerCase() === "use-credentials" ? "credentials" : "anonymous";
+        if (url.protocol === "https:" || url.protocol === "http:")
+            tags.push({ src: url, integrity, cors });
+    }
+    return tags;
+}
+/** Why a browser refuses the runtime on this page, or null: the first of
+    its tags that it refuses. The file's digest is known without the
+    network only where servedFile says which file an address serves: a
+    file next to the pages (hashed here) or a release on an npm CDN
+    (VANILLA_DIGESTS, or an installed package's dist/mapled.js.sha384) —
+    anything else isn't checked. */
+async function refusalOn(text, rel, dir, site) {
+    let origin = NOWHERE;
+    try {
+        if (site)
+            origin = new URL(site).origin;
+    }
+    catch {
+        origin = NOWHERE;
+    }
+    let tags;
+    try {
+        tags = runtimeTagsOf(text, new URL(htmlPage(rel).route, origin));
+    }
+    catch {
+        // deeper than a browser builds, or unreadable: nothing on it is claimed
+        return null;
+    }
+    for (const tag of tags) {
+        const other = tag.src.origin !== origin;
+        // with credentials, a CORS answer passes only when it names the page's origin; these CDNs answer "*" — integrity or not
+        if (other && tag.cors === "credentials" && NPM_CDNS.has(tag.src.hostname))
+            return { credentials: true };
+        const sri = sriOf(tag.integrity);
+        if (!sri.checked)
+            continue;
+        if (other && tag.cors === "none")
+            return { cors: true };
+        const file = sri.strongest ? servedFile(tag.src, origin) : null;
+        if (!sri.strongest || !file)
+            continue;
+        const known = "copy" in file ? await copyDigest(dir, file.copy, sri.strongest.hash) : await releasedDigest(dir, file.version, sri.strongest.hash);
+        if (known && !sri.strongest.digests.some((d) => d.equals(known.digest)))
+            return { digest: `${sri.strongest.hash}-${known.digest.toString("base64")}`, of: known.of };
+    }
+    return null;
+}
+/** The npm CDNs that serve a package's file as it was published, and the path a package starts at on each: a
+    release's digest holds only there — any other host may serve a file of its own under the same path. */
+const NPM_CDNS = new Map([
+    ["cdn.jsdelivr.net", "/npm/"],
+    ["unpkg.com", "/"],
+]);
+/** Which file's bytes an address serves, where doctor knows them without
+    the network — the one place that decides whether a digest is checked:
+    a path on the site's own origin (a file of the repository, if there is
+    one), or the published runtime of a release on an npm CDN, at its
+    canonical address (https, no port of its own). Either only when the
+    path alone decides the answer: no query (unpkg's `?meta` answers with
+    JSON, a server may answer `?v=2` with anything) and no credentials;
+    the fragment never leaves the browser. Null for anything else. */
+export function servedFile(src, origin) {
+    const sent = new URL(src.href);
+    sent.hash = "";
+    if (sent.href.includes("?") || sent.username !== "" || sent.password !== "")
+        return null;
+    if (sent.origin === origin) {
+        try {
+            return { copy: decodeURIComponent(sent.pathname) };
+        }
+        catch {
+            return null;
+        }
+    }
+    const root = sent.protocol === "https:" && sent.port === "" ? NPM_CDNS.get(sent.hostname) : undefined;
+    if (root === undefined || !sent.pathname.startsWith(root))
+        return null;
+    const version = /^@mapled\/vanilla@(\d+\.\d+\.\d+)\/dist\/mapled\.js$/.exec(sent.pathname.slice(root.length))?.[1];
+    return version ? { version } : null;
+}
+/** The digest of the file a path of the site names, when it sits in the repository (or its public/). */
+async function copyDigest(dir, served, hash) {
+    for (const at of [path.resolve(dir), path.resolve(dir, "public")]) {
+        const file = path.join(at, served);
+        if (!file.startsWith(at + path.sep))
+            continue;
+        const bytes = await readFile(file).catch(() => null);
+        if (bytes && bytes.length <= 8 * 1024 * 1024)
+            return { digest: createHash(hash).update(bytes).digest(), of: path.relative(dir, file).split(path.sep).join("/") };
+    }
+    return null;
+}
+/** The digest of a release's runtime file: sha384 is the only one published. */
+async function releasedDigest(dir, version, hash) {
+    if (hash !== "sha384")
+        return null;
+    let value = VANILLA_DIGESTS[version];
+    if (value === undefined) {
+        // a version newer than this CLI: the package installed next to the pages, if it is that version
+        const pkg = path.join(dir, "node_modules", "@mapled", "vanilla");
+        const installed = await readFile(path.join(pkg, "package.json"), "utf8")
+            .then((raw) => JSON.parse(raw).version)
+            .catch(() => null);
+        if (installed === version)
+            value = (await readFile(path.join(pkg, "dist", "mapled.js.sha384"), "utf8").catch(() => "")).trim();
+    }
+    if (!value || !/^sha384-[A-Za-z0-9+/]{64}$/.test(value))
+        return null;
+    return { digest: Buffer.from(value.slice("sha384-".length), "base64"), of: `@mapled/vanilla ${version}` };
+}
+function refusalText(r) {
+    const more = r.more === 0 ? "" : ` ${r.more} more page${r.more === 1 ? " has" : "s have"} a tag a browser refuses.`;
+    if ("credentials" in r) {
+        return `${r.file} loads it with crossorigin="use-credentials" — jsDelivr and unpkg answer every origin with "*", which a browser doesn't take for a request with credentials, so it refuses the runtime and the page shows only its own HTML. Use crossorigin="anonymous".${more}`;
+    }
+    if ("cors" in r) {
+        return `${r.file} loads it with integrity and without crossorigin — a browser checks a file from another origin only when it came with CORS, so it refuses the runtime and the page shows only its own HTML. Add crossorigin="anonymous" to the script tag.${more}`;
     }
-    return unpinned === null ? null : { file: unpinned, version: null };
+    return `The integrity in ${r.file} isn't the digest of ${r.of} — a browser refuses the file, and the page shows only its own HTML. Use integrity="${r.digest}".${more}`;
 }
 export function checkScriptTag(tag, latest) {
     const key = "sdk";
@@ -160,6 +384,9 @@ export function checkScriptTag(tag, latest) {
             detail: `No page loads it yet. Put <script src="https://cdn.jsdelivr.net/npm/@mapled/vanilla@${at}/dist/mapled.js" data-mapled-key="…" defer></script> into the pages.`,
         };
     }
+    // before the version: a tag that doesn't run is worse than an old one
+    if (tag.refused)
+        return { key, label, status: "warning", detail: refusalText(tag.refused) };
     if (tag.version === null) {
         return { key, label, status: "warning", detail: `${tag.file} loads it without a version — that address follows every release. Pin it: @mapled/vanilla@${at}.` };
     }

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/report.d.ts

@@ -122,6 +122,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/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.d.ts

@@ -0,0 +1,8 @@
+/** Subresource Integrity of "@mapled/vanilla"'s single file for each
+    released version — `dist/mapled.js.sha384` of the package. `doctor`
+    checks a page's `integrity` against it without asking the network.
+    The same table as VANILLA_INTEGRITY of the API (lib/siteStack.ts),
+    which siteStack.test.ts compares with this one: a release of the
+    runtime adds its line in both. A version this CLI doesn't know yet is
+    read from an installed package, or its digest isn't checked. */
+export declare const VANILLA_DIGESTS: Readonly<Record<string, string>>;

package/dist/vanillaDigests.js

@@ -0,0 +1,14 @@
+/** Subresource Integrity of "@mapled/vanilla"'s single file for each
+    released version — `dist/mapled.js.sha384` of the package. `doctor`
+    checks a page's `integrity` against it without asking the network.
+    The same table as VANILLA_INTEGRITY of the API (lib/siteStack.ts),
+    which siteStack.test.ts compares with this one: a release of the
+    runtime adds its line in both. A version this CLI doesn't know yet is
+    read from an installed package, or its digest isn't checked. */
+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",
+};

package/package.json

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