@mapled/cli 0.11.0 → 0.13.0

package/README.md

@@ -128,6 +128,8 @@ Scanned 2 HTML files — 2 pages, 11 bindings.
 ⚠ This path names nothing in the schema: home.tagline (index.html). A misspelled field empties its place on the page, a misspelled single leaves the page's own HTML.
 ```
 
+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`, 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.
+
 `--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
@@ -193,6 +195,7 @@ Mapled doctor — Dolphin Landing
 ✓ mapled CLI           0.9.0 (current)
 ✓ Revalidation route   app/api/mapled/revalidate/route.ts
 ⚠ Preview route        app/api/mapled/preview/route.ts is missing — mount createPreviewHandler from "@mapled/next/server" so Preview from Mapled works.
+✓ Live updates         app/api/mapled/release/route.ts — open tabs follow Publish (<MapledLive /> in app/layout.tsx)
 ✓ Site reads content   Last read 3m ago
 ✓ Publish webhook      Delivered 2h ago to dolphin-landing.example
 ✓ Preview on the site  Responds at https://dolphin-landing.example/api/mapled/preview
@@ -201,9 +204,9 @@ Mapled doctor — Dolphin Landing
 1 warning.
 ```
 
-The repository side: the link, the sign-in, the generated types, the schema pin, the site manifest (and whether it matches what was pushed), the integration hash — one line saying whether the pin and the manifest here describe the same integration Mapled holds, and if not, what moved (the schema, the bindings, or edits made in Mapled) and which command catches up — `MAPLED.md` (and whether it is what Mapled would render now), `MAPLED_KEY` and `MAPLED_WEBHOOK_SECRET` in your env files (names only — values are never read out), env files or Mapled secrets tracked by git, the installed `@mapled/next` and CLI versions, the revalidation and preview routes of a Next.js site. The Mapled side, from the same status the AI agent's `check_integration` tool reads: whether the site has read content with the delivery key, the publish webhook and its last delivery, the preview route on the deployed site, the bindings health.
+The repository side: the link, the sign-in, the generated types, the schema pin, the site manifest (and whether it matches what was pushed), the integration hash — one line saying whether the pin and the manifest here describe the same integration Mapled holds, and if not, what moved (the schema, the bindings, or edits made in Mapled) and which command catches up — `MAPLED.md` (and whether it is what Mapled would render now), `MAPLED_KEY` and `MAPLED_WEBHOOK_SECRET` in your env files (names only — values are never read out), env files or Mapled secrets tracked by git, the installed `@mapled/next` and CLI versions, the revalidation and preview routes of a Next.js site, and its live updates — ○ «Not used» while no page mounts `<MapledLive />` or calls `watchRelease`, ✓ when the route they ask answers its `GET` with `createReleaseHandler` (`GET` is the handler, or always returns its call: every return is that call, the last statement is one, and nothing throws), ⚠ when it is missing (the tabs would poll a 404) with the file to add, when the route's `GET` isn't seen to answer with the handler (exported as `POST` they would get a 405; a `GET` that only mentions it, calls it and returns something else, or answers something else on another branch, answers without the release), or when no route can be checked against the endpoint — it is relative to the page, a full address (the tab asks it as written, and doctor can't tell it's the site's own), computed, or comes from spread props; a path from the site's root is checked against the route the App Router picks for it, dynamic and catch-all folders included, among route files with the site's page extensions (`pageExtensions` in next.config; `tsx`, `ts`, `jsx`, `js` by default) and under its `basePath`; ⚠ too when a page of either router, more specific than the route, takes that path first, when the dynamic route that answers sets `dynamicParams`, when the route may set `dynamic` to anything but `"auto"` or `"force-dynamic"` (a copy Next builds without the tab's request), sets `"force-dynamic"` while `createReleaseHandler` there isn't seen to keep a `revalidate` above 0 (its default does; with `false` or `0` Next reads the release past the cache tag) or `fetchCache` to anything but `"auto"` (the release read past the cache tag, before the webhook refreshes the pages), when next.config sets `output: "export"` (no server runs the route), or when next.config may set `pageExtensions`, `basePath` or `output` where doctor can't read them — it reads them only as literals, once, in the object the file exports, and only while the file is declarative: type imports, declarations of data, one export of the config object itself, and functions only as Next's hooks (`webpack`, `headers` …) in it. A module the file loads (a plugin such as `withMDX`, a `path` helper, an env check), a config exported as a function, any other code, a spread or a getter leaves the config unread. With a `basePath`, a listener that gives no endpoint asks under it from `@mapled/next` 0.10.0 — doctor reads the version the site has installed, and it's a ⚠ when that is older or missing. A `middleware` file (`proxy` in Next 16) next to the folder Next reads is a ⚠ unless its matcher, read the way Next's build reads `export const config`, surely leaves the route's path alone: it has no matcher, doctor can't read it, a source may take the path, or next.config has locales (`i18n`). `src/app` or `src/pages` counts only when the root has no `app` or `pages`, as Next reads them. 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. 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 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.
 

package/dist/commands.js

@@ -12,6 +12,7 @@ import { formatChecks, GLYPH, paint, summarize, useColor } from "./output.js";
 import { diffSchema, formatChanges, pinSchema, readPin, SCHEMA_FILE, summarizeChanges, writePin } from "./pin.js";
 import { checkMapledMd, MD_FILE, mergeMd } from "./md.js";
 import { buildReport, clean, formatReport, isChecked, linkLifetime, pickRun, } from "./report.js";
+import { capabilitiesOf, findLive, liveState } from "./live.js";
 import { loadTypeScript, mergeManifest, scanRepository } from "./scan.js";
 import { scanHtml } from "./scanHtml.js";
 import { generateTypes } from "./types.js";
@@ -358,7 +359,8 @@ export async function bindingsPull(ctx, flags) {
     const local = await loadManifest(found.dir);
     if (local && !flags.force) {
         const diff = compareManifests(local.manifest, stored.manifest);
-        if (!diff.same) {
+        // capabilities a scan just recorded are as much the repository's as its bindings
+        if (!diff.same || diff.capabilitiesDiffer) {
             const parts = [];
             if (diff.onlyLocal.length > 0)
                 parts.push(`${diff.onlyLocal.length} not pushed`);
@@ -366,6 +368,8 @@ export async function bindingsPull(ctx, flags) {
                 parts.push(`${diff.changed.length} changed`);
             if (diff.onlyRemote.length > 0)
                 parts.push(`${diff.onlyRemote.length} only in Mapled`);
+            if (diff.capabilitiesDiffer)
+                parts.push("capabilities 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\`.`);
         }
     }
@@ -573,6 +577,13 @@ export async function scan(ctx, flags) {
     const framework = found.config.framework ?? (await dr.detectFramework(found.dir)) ?? null;
     // a plain HTML site declares its reads in attributes, not in code
     const result = framework === "plain-html" ? await scanHtml(found.dir, { schema }) : await scanRepository(found.dir, { framework, schema, ts: loadTypeScript(found.dir) });
+    // live updates (§18.8) of a Next.js site: the same reading of the code as doctor's line
+    const live = framework === "nextjs" ? liveState(await findLive(found.dir)) : null;
+    if (live)
+        result.capabilities = capabilitiesOf(live);
+    if (live && live.kind !== "served" && live.kind !== "unused") {
+        result.notes.push(`${live.listener.via} in ${live.listener.file} has no route that doctor can confirm answers it, so the manifest records that the site doesn't follow Publish — \`mapled doctor\` says what to fix.`);
+    }
     const existing = await loadManifest(found.dir);
     const merged = mergeManifest(existing?.manifest ?? null, result, { prune: Boolean(flags.prune) });
     if (flags.json) {
@@ -587,6 +598,10 @@ export async function scan(ctx, flags) {
         for (const line of describeScan(result, schema))
             ctx.out(line);
     }
+    if (live?.kind === "served") {
+        ctx.out("");
+        ctx.out(`Live updates: ${live.listener.via} in ${live.listener.file} → ${live.path} (${live.route.file})`);
+    }
     if (result.notes.length > 0) {
         ctx.out("");
         for (const n of result.notes)
@@ -604,6 +619,8 @@ export async function scan(ctx, flags) {
             parts.push(`${merged.changed.length} changed`);
         if (merged.unchanged.length > 0)
             parts.push(`${merged.unchanged.length} unchanged`);
+        if (merged.capabilitiesChanged)
+            parts.push("capabilities updated");
         ctx.out(`Wrote ${MANIFEST_FILE} — ${manifestSummary(merged.manifest)}${parts.length > 0 && existing ? ` (${parts.join(", ")})` : ""}.${keptNote}${droppedNote}`);
         ctx.out("Next: `mapled bindings push`.");
     }
@@ -617,10 +634,12 @@ export async function scan(ctx, flags) {
         if (merged.changed.length > 0)
             parts.push(`${merged.changed.length} changed`);
         parts.push(`${merged.unchanged.length} unchanged`);
+        if (merged.capabilitiesChanged)
+            parts.push("capabilities 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) {
+        if (merged.added.length > 0 || merged.changed.length > 0 || merged.capabilitiesChanged) {
             ctx.out(`Run \`mapled scan --write\` to update ${MANIFEST_FILE}, then \`mapled bindings push\`.`);
         }
         else {
@@ -693,6 +712,8 @@ export async function doctor(ctx, flags) {
     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 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));
     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

@@ -1,4 +1,5 @@
 import type { Connection } from "./credentials.js";
+import { type LiveFacts } from "./live.js";
 import { type Manifest, type Problem } from "./manifest.js";
 import type { Fetch } from "./oauth.js";
 import { type SchemaChange, type SchemaPin } from "./pin.js";
@@ -145,6 +146,10 @@ 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;
+/** 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). */
+export declare function checkLive(facts: LiveFacts | null, framework: string | undefined): Check;
 export declare function checkReads(lastReadAt: string | null): Check;
 export declare function checkWebhook(webhook: IntegrationStatus["webhook"], site?: {
     local: boolean;

package/dist/doctor.js

@@ -3,6 +3,7 @@ import { access, readdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
 import { integrationHash } from "./integrationHash.js";
+import { BASE_PATH_SINCE, fullAddress, liveState, RELEASE_ROUTE, routeFileFor } from "./live.js";
 import { compareManifests, manifestSummary, MANIFEST_FILE } from "./manifest.js";
 import { SCHEMA_FILE } from "./pin.js";
 import { splitGenerated } from "./types.js";
@@ -448,6 +449,146 @@ export function checkRoute(kind, found, framework) {
     }
     return { key, label, status: "passed", detail: found.file };
 }
+/** 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). */
+export function checkLive(facts, framework) {
+    const key = "live";
+    const label = "Live updates";
+    if (framework === "react-spa") {
+        return { key, label, status: "skipped", detail: "No route needed: `live` on MapledProvider (watchRelease by key) asks Mapled directly." };
+    }
+    if (framework === "plain-html") {
+        return { key, label, status: "skipped", detail: "No route needed: data-mapled-live on the script tag (watchRelease by key) asks Mapled directly." };
+    }
+    if ((framework && framework !== "nextjs") || !facts) {
+        return { key, label, status: "skipped", detail: `No live updates check for ${framework ?? "this"} site${framework ? "s" : ""} yet.` };
+    }
+    const state = liveState(facts);
+    const who = (l) => `${l.via} in ${l.file}`;
+    const handler = 'createReleaseHandler from "@mapled/next/server"';
+    switch (state.kind) {
+        case "unused":
+            return {
+                key,
+                label,
+                status: "skipped",
+                detail: state.handlerRoute
+                    ? `Not used: ${state.handlerRoute.file} is mounted, but no page listens — add <MapledLive /> to the root layout.`
+                    : "Not used: an open tab shows a publish once it is reloaded.",
+            };
+        case "served":
+            return { key, label, status: "passed", detail: `${state.route.file} — open tabs follow Publish (${who(state.listener)})` };
+        case "no_handler":
+            return { key, label, status: "warning", detail: `${state.route.file} exists but doesn't use ${handler} — ${who(state.listener)} can't read the release there.` };
+        case "not_get":
+            return {
+                key,
+                label,
+                status: "warning",
+                detail: `${state.route.file} calls ${handler}, but doctor can't see its GET always answer with the handler's response — ${who(state.listener)} asks with GET. Export the handler as GET, or end GET by returning its call, with no other return or throw.`,
+            };
+        case "unresolved":
+            return {
+                key,
+                label,
+                status: "warning",
+                detail: state.listener.endpoint === null
+                    ? `${who(state.listener)} takes its endpoint from the code (a computed value or spread props), so no route can be checked. Give the route's path, like ${RELEASE_ROUTE}.`
+                    : fullAddress(state.listener.endpoint)
+                        ? `${who(state.listener)} asks ${state.listener.endpoint}, a full address — the tab asks it as written, and doctor can't tell it's this site's own, so no route can be checked. Give the route's path, like ${RELEASE_ROUTE}.`
+                        : `${who(state.listener)} asks ${state.listener.endpoint}, which isn't a path from the site's root — each page resolves it against its own address, so no route can be checked. Give the route's path, like ${RELEASE_ROUTE}.`,
+            };
+        case "config":
+            return {
+                key,
+                label,
+                status: "warning",
+                detail: `${state.file} may set pageExtensions, basePath or output where doctor can't read them — code that runs as Next loads it, a plugin's or a function's result, a value or name the code builds, an object from another file or spread in — so no route can be checked for ${who(state.listener)}. Write them as literals in the object it exports, or leave them out.`,
+            };
+        case "export":
+            return {
+                key,
+                label,
+                status: "warning",
+                detail: state.output === "export"
+                    ? `${state.file} sets output: "export" — a static export has no server, so no route answers ${who(state.listener)}, and open tabs can't follow Publish. Live updates need the site served by Next: next start, or a host that runs it.`
+                    : `${state.file} may set output where doctor can't read it — with output: "export" the site has no server, and no route answers ${who(state.listener)}. Write output as a literal in the object it exports, or leave it out.`,
+            };
+        case "outside":
+            return {
+                key,
+                label,
+                status: "warning",
+                detail: `${who(state.listener)} asks ${state.endpoint}, outside the site's basePath ${state.basePath} — Next answers nothing there. Give it the path under the basePath: ${state.basePath}${state.endpoint === "/" ? "" : state.endpoint}.`,
+            };
+        case "default_base":
+            return {
+                key,
+                label,
+                status: "warning",
+                detail: state.sdk === null
+                    ? `${who(state.listener)} gives no endpoint, and doctor finds no @mapled/next in node_modules to tell where it asks: from ${BASE_PATH_SINCE} under the site's basePath (${state.basePath}${RELEASE_ROUTE}), before that at ${RELEASE_ROUTE}, where Next answers nothing. Run npm install, or give it the path: ${state.basePath}${RELEASE_ROUTE}.`
+                    : `${who(state.listener)} gives no endpoint, so @mapled/next ${state.sdk} asks ${RELEASE_ROUTE}, outside the site's basePath ${state.basePath} — Next answers nothing there. Update to @mapled/next ${BASE_PATH_SINCE} or later, which asks under the basePath, or give it the path: ${state.basePath}${RELEASE_ROUTE}.`,
+            };
+        case "taken":
+            return {
+                key,
+                label,
+                status: "warning",
+                detail: `${who(state.listener)} asks ${state.endpoint}, which ${state.page.file} answers, not a release route. Point the listener at a path of its own, and mount ${handler} there.`,
+            };
+        case "params":
+            return {
+                key,
+                label,
+                status: "warning",
+                detail: `${state.route.file} sets dynamicParams, so it answers only the params its code lists — doctor can't tell ${state.endpoint} is one, and ${who(state.listener)} may get a 404 there. Mount ${handler} at ${routeFileFor(state.endpoint, facts)}.`,
+            };
+        case "segment":
+            return {
+                key,
+                label,
+                status: "warning",
+                detail: state.setting === "dynamic"
+                    ? `${state.route.file} may set dynamic to something other than "auto" or "force-dynamic" — with "force-static" Next serves a copy of the route built without the tab's request, which moves only when Next rebuilds it and answers every check in full, so doctor can't tell ${who(state.listener)} follows Publish. Leave dynamic out of the route.`
+                    : state.setting === "force-dynamic"
+                        ? `${state.route.file} sets dynamic to "force-dynamic", and doctor can't see createReleaseHandler there keep a revalidate above 0 (false, 0, or options it can't read) — Next then reads the live release past the cache tag, so the route moves before the webhook refreshes the pages, and ${who(state.listener)} refreshes into a release they don't show yet. Leave dynamic out of the route, or revalidate at its default.`
+                        : `${state.route.file} may set fetchCache to something other than "auto" — with "force-no-store" the handler reads the live release past the cache tag, so the route moves before the webhook refreshes the pages, and ${who(state.listener)} refreshes into a release they don't show yet. Leave fetchCache out of the route.`,
+            };
+        case "middleware": {
+            const base = facts.basePath ?? "";
+            const local = base !== "" && state.path.startsWith(base) ? state.path.slice(base.length) || "/" : state.path;
+            const why = state.reason === "none"
+                ? `${state.file} has no matcher, so it runs on every path, ${state.path} included`
+                : state.reason === "unread"
+                    ? `doctor can't read the matcher of ${state.file} — Next reads it only from export const config = { matcher: … } written with literals — so it may run on ${state.path}`
+                    : state.reason === "i18n"
+                        ? `${state.file} may run on ${state.path}: with i18n in next.config Next puts a locale in front of its matcher, and doctor can't tell which paths it takes`
+                        : `${state.file} may run on ${state.path}: its matcher ${JSON.stringify(state.source)} can take it`;
+            return {
+                key,
+                label,
+                status: "warning",
+                detail: `${why}. doctor can't see what it does there — a redirect, a rewrite or a sign-in wall keeps ${who(state.listener)} from the release. Leave the path out of its matcher, like "/((?!${local.slice(1)}).*)".`,
+            };
+        }
+        case "missing":
+            return state.endpoint === null
+                ? {
+                    key,
+                    label,
+                    status: "warning",
+                    detail: `${who(state.listener)} asks a release route the code doesn't have — mount ${handler} (at ${routeFileFor(RELEASE_ROUTE, facts)} by default).`,
+                }
+                : {
+                    key,
+                    label,
+                    status: "warning",
+                    detail: `${who(state.listener)} asks ${state.endpoint}, which has no route — mount ${handler} at ${routeFileFor(state.endpoint, facts)}.`,
+                };
+    }
+}
 export function checkReads(lastReadAt) {
     const label = "Site reads content";
     if (!lastReadAt) {
@@ -606,7 +747,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) {
+    if (diff.same && !diff.capabilitiesDiffer) {
         return { key: "manifest", label, status: "passed", detail: `${MANIFEST_FILE} is pushed as manifest v${remote.version} (${manifestSummary(local.manifest)})` };
     }
     const parts = [];
@@ -616,6 +757,9 @@ export function checkManifestFile(local, remote) {
         parts.push(`${diff.changed.length} changed`);
     if (diff.onlyRemote.length > 0)
         parts.push(`${diff.onlyRemote.length} only in Mapled`);
+    // capabilities aren't in the integration hash, so this is the line that notices them
+    if (diff.capabilitiesDiffer)
+        parts.push("capabilities changed");
     return {
         key: "manifest",
         label,

package/dist/live.d.ts

@@ -0,0 +1,264 @@
+/** Live updates (§18.8) as the site's code shows them. A Next.js site
+    follows Publish in open tabs with two pieces: `<MapledLive />` from
+    "@mapled/next/live" (or `watchRelease` from "@mapled/next") asks a
+    route of the site every few seconds, and that route answers with
+    `createReleaseHandler` from "@mapled/next/server". A listener without
+    the route polls a 404 forever and nothing says so — `mapled doctor`
+    reads both and says which is missing, and `mapled scan` records the
+    result in the manifest (`capabilities.realtime`, `releaseRoute`) so
+    MAPLED.md can tell the next agent. The code is read with the scanner's
+    tokenizer: comments and strings never count as a use, and neither
+    does an imported name the file binds again. */
+/** Where `<MapledLive />` and `watchRelease` ask when no endpoint is given. */
+export declare const RELEASE_ROUTE = "/api/mapled/release";
+/** The `@mapled/next` from which that default follows the site's basePath —
+    before it, a listener with no endpoint asks RELEASE_ROUTE as written. */
+export declare const BASE_PATH_SINCE = "0.10.0";
+export type LiveListener = {
+    file: string;
+    via: "<MapledLive />" | "watchRelease";
+    /** the endpoint as the code writes it; null when the code decides it —
+        a computed value, or spread props or options that may carry one */
+    endpoint: string | null;
+    /** the code gives no endpoint: the SDK asks its default, `endpoint` —
+        under the site's basePath from `@mapled/next` 0.10.0 */
+    byDefault?: true;
+};
+/** An App Router route handler file and the path it answers. `handler`:
+    "GET" when the route's exported GET is seen to answer with
+    `createReleaseHandler`, "other" when the file calls it but GET isn't
+    (exported as POST or not at all — the tab's GET gets a 405 — or a GET
+    whose answer isn't the handler's), null when it doesn't call it.
+    `params`: the file sets `dynamicParams` — a dynamic route then answers
+    only the params its code lists. `segment`: the first route segment
+    setting the file may export as a value that changes how Next serves or
+    caches the route (SEGMENT_SETTINGS). */
+export type RouteFile = {
+    file: string;
+    path: string;
+    handler: RouteHandler;
+    params?: true;
+    segment?: SegmentSetting;
+};
+export type RouteHandler = "GET" | "other" | null;
+/** A page file and the path it answers: an App Router `page.<ext>`, or any
+    Pages Router file (`pages/api/…` included). It takes part in the match
+    as Next makes it — a page more specific than a route takes the path. */
+export type PageFile = {
+    file: string;
+    path: string;
+};
+/** `routeExtension`: what a route file the site lacks would end in — the
+    site's page extension, `ts` by default. `appDir`: the App Router folder
+    Next reads, when the site has one. `basePath`: what every path of the
+    site starts with (next.config). `config`: the next.config file, when it
+    may set `pageExtensions` or `basePath` where the reading can't follow —
+    then no route can be checked. `sdk`: the `@mapled/next` version the
+    site resolves, as Node finds the package from the site's folder up —
+    absent when none is installed. `output`: next.config sets `output:
+    "export"` (value "export") or may set it where the reading can't tell
+    (null) — then there may be no server to run any route. */
+export type LiveFacts = {
+    listeners: LiveListener[];
+    routes: RouteFile[];
+    pages?: PageFile[];
+    routeExtension?: string;
+    appDir?: string;
+    basePath?: string;
+    config?: string;
+    sdk?: string;
+    output?: {
+        file: string;
+        value: "export" | null;
+    };
+    middleware?: Middleware[];
+    i18n?: true;
+};
+/** A middleware file of the site (`proxy` from Next 16) and the paths it
+    runs on as Next reads its `config`: the matcher's sources, "none" when
+    it has no matcher — every path — or "unread" when Next may not read the
+    config doctor sees, or doctor can't read it. */
+export type Middleware = {
+    file: string;
+    matcher: string[] | "none" | "unread";
+};
+export type LiveState = {
+    kind: "unused";
+    handlerRoute: RouteFile | null;
+} | {
+    kind: "served";
+    listener: LiveListener;
+    route: RouteFile;
+    path: string;
+} | {
+    kind: "missing";
+    listener: LiveListener;
+    endpoint: string | null;
+} | {
+    kind: "unresolved";
+    listener: LiveListener;
+} | {
+    kind: "no_handler";
+    listener: LiveListener;
+    route: RouteFile;
+} | {
+    kind: "not_get";
+    listener: LiveListener;
+    route: RouteFile;
+} | {
+    kind: "config";
+    listener: LiveListener;
+    file: string;
+} | {
+    kind: "outside";
+    listener: LiveListener;
+    endpoint: string;
+    basePath: string;
+} | {
+    kind: "default_base";
+    listener: LiveListener;
+    basePath: string;
+    sdk: string | null;
+} | {
+    kind: "export";
+    listener: LiveListener;
+    file: string;
+    output: "export" | null;
+} | {
+    kind: "middleware";
+    listener: LiveListener;
+    route: RouteFile;
+    path: string;
+    file: string;
+    reason: "none" | "unread" | "i18n" | "matcher";
+    source?: string;
+} | {
+    kind: "taken";
+    listener: LiveListener;
+    page: PageFile;
+    endpoint: string;
+} | {
+    kind: "params";
+    listener: LiveListener;
+    route: RouteFile;
+    endpoint: string;
+} | {
+    kind: "segment";
+    listener: LiveListener;
+    route: RouteFile;
+    setting: SegmentSetting;
+};
+/** What the manifest records (§21.2). */
+export type Capabilities = {
+    realtime?: boolean;
+    releaseRoute?: string;
+};
+/** The extensions a route file may have when next.config doesn't set `pageExtensions`. */
+export declare const PAGE_EXTENSIONS: string[];
+/** The listeners one file mounts and, for a route file, whether its GET
+    serves the release. An imported name the file binds again — a
+    parameter, a declaration, destructuring — may not be the import where
+    it's used, and the reading can't tell where: none of its uses count.
+    A namespace's name the same: its members count only where `ns` itself
+    is the import. */
+export declare function liveInFile(file: string, text: string): {
+    listeners: LiveListener[];
+    handler: RouteHandler;
+    params: boolean;
+    segment?: SegmentSetting;
+};
+/** 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,
+    and `fetchCache` can make the handler's read skip the `mapled` cache
+    tag, so the release moves before the webhook refreshes the pages.
+    `revalidate` isn't one: it only fills in fetches that don't name their
+    own window, and the handler's names one (Next 14's fetch patch; the
+    live smoke with `revalidate = 1` on Next 15). "force-dynamic" is the
+    third: harmless while the handler keeps its read's window, and past
+    the tag when it doesn't (keepsWindow). */
+export declare const SEGMENT_SETTINGS: readonly ["dynamic", "fetchCache"];
+export type SegmentSetting = (typeof SEGMENT_SETTINGS)[number] | "force-dynamic";
+/** The route files of the App Router with the path each answers. */
+export declare function routeFileOf(file: string, extensions?: string[]): string | null;
+/** The page files of both routers with the path each answers: an App
+    Router `page.<ext>`, and any Pages Router file but `_app`, `_document`
+    and `_error`, with the longest page extension its name ends in taken
+    off, as Next does, and `index` naming its folder. */
+export declare function pageFileOf(file: string, extensions?: string[]): string | null;
+/** What next.config decides about where a file answers: the page
+    extensions of route and page files, and the basePath every path of the
+    site starts with. `output`, when the file may set it: the literal, or
+    null where the reading can't tell — with "export" there is no server.
+    `i18n`: the file mentions it, so locales may be configured. */
+export type NextConfig = {
+    pageExtensions: string[];
+    basePath: string;
+    output?: string | null;
+    i18n?: true;
+};
+/** next.config's `pageExtensions`, `basePath` and `output`, read only when
+    the file is written in a declarative subset of JavaScript, where no code
+    runs while Next loads it — neither the file's nor a module's:
+
+    - statements: type imports (`import type { NextConfig } from "next"`),
+      declarations, and one export of the config object itself —
+      `module.exports = {…}`, `export default nextConfig` or `export {
+      config as default }`;
+    - values: literals, and arrays and objects of them, `process.env.NAME`,
+      `process.cwd()`, `__dirname`, `import.meta.dirname`, `new URL(…)`,
+      `require.resolve("…")`, names declared so; `!`, `+`, comparisons,
+      `&&`, `||`, `??` and `? :` over them; a type after `as` or
+      `satisfies`;
+    - functions only as Next's hooks (`webpack`, `headers`, `redirects`,
+      `rewrites`, `generateBuildId`, `exportPathMap`) at the top of the
+      exported object: Next calls them once it has loaded the config.
+
+    Anything else makes it null: a module loaded in any way (`import "…"`,
+    `import x from "…"`, `require(…)`) — its code runs, and which module a
+    name loads its spelling doesn't show (Node's self-reference, a
+    next.config.ts's tsconfig `paths`); so a plugin's call around the
+    config (`withMDX(nextConfig)`) and a `path` helper too (block 348). And
+    any other statement, a function or class of the file, a getter, a
+    spread, a member of a value, a call, a name bound twice or over one the
+    subset reads (`require`, `process`), the config's name used twice. Each
+    setting: a literal, once, in that object — `pageExtensions` or
+    `basePath` named anywhere else in the file makes it null, and an
+    `output` the reading can't take (an expression, a second one, one a
+    hook's code writes) makes only `output` null. `live.test.ts` holds the
+    reading to Next's own `loadConfig` over generated configs.
+
+    What the reading trusts: Next calls the hooks only after loading, and a
+    hook leaves the settings it loaded alone. */
+export declare function nextConfigOf(config: string | null): NextConfig | null;
+/** The matcher of a middleware file, read as Next's build reads it: only
+    `export const config = { … }` (a type or `satisfies` allowed), every
+    value in it a literal (extractable), `matcher` a string or an array of
+    strings and `{ source }` objects. Anything else Next can't read either
+    and runs the middleware on every path — or reads what doctor can't. */
+export declare function middlewareMatcher(text: string): string[] | "none" | "unread";
+/** Whether a matcher source may take the path `at` (without the basePath,
+    which Next puts in front of both). False only when it surely can't: the
+    literal the source starts with isn't how the path starts, or right
+    after it comes a group — path-to-regexp's `(…)`, kept verbatim in the
+    regex Next builds — that matches no start of the rest, in either case.
+    Everything else may. */
+export declare function sourceMayTake(source: string, at: string): boolean;
+/** Whether a version is at least `min`, by its major, minor and patch —
+    false for one that doesn't start with three numbers. */
+export declare function atLeast(version: string, min: string): boolean;
+export declare function findLive(dir: string, maxFiles?: number): Promise<LiveFacts>;
+/** Whether a literal endpoint names its own origin — `https://…`, `//host/…`
+    — which the code doesn't show to be the site's: `watchRelease` fetches it
+    as written, and no route file of this site is known to answer it. */
+export declare const fullAddress: (endpoint: string) => boolean;
+/** Whether every listener has a route that answers it. The first one
+    that doesn't is the one to name. */
+export declare function liveState(facts: LiveFacts): LiveState;
+/** What `mapled scan` writes into the manifest: a listener nothing answers
+    isn't listening; the route is the path the tab asks, not a dynamic route's pattern. */
+export declare function capabilitiesOf(state: LiveState): Capabilities;
+/** Where a route answering `endpoint` goes: in the App Router folder Next
+    reads — without one, under `src/app` when the site keeps its code there
+    — and without the basePath, which Next adds itself. */
+export declare function routeFileFor(endpoint: string, facts: LiveFacts): string;