@mapled/cli 0.12.0 → 0.14.0

package/README.md

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

package/dist/doctor.js

@@ -3,7 +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 { fullAddress, liveState, RELEASE_ROUTE, routeFileFor } from "./live.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 { splitGenerated } from "./types.js";
@@ -467,6 +467,10 @@ export function checkLive(facts, framework) {
     const state = liveState(facts);
     const who = (l) => `${l.via} in ${l.file}`;
     const handler = 'createReleaseHandler from "@mapled/next/server"';
+    // the Pages Router's: the default export of an API route
+    const pagesHandler = 'createPagesReleaseHandler from "@mapled/next/server"';
+    const handlerOf = (route) => (route.router === "pages" ? pagesHandler : handler);
+    const app = `${facts.pagesDir ?? "pages"}/_app`;
     switch (state.kind) {
         case "unused":
             return {
@@ -474,19 +478,46 @@ export function checkLive(facts, framework) {
                 label,
                 status: "skipped",
                 detail: state.handlerRoute
-                    ? `Not used: ${state.handlerRoute.file} is mounted, but no page listens — add <MapledLive /> to the root layout.`
+                    ? state.handlerRoute.router === "pages"
+                        ? `Not used: ${state.handlerRoute.file} is mounted, but no page listens — add <MapledLive /> from "@mapled/next/live/pages" to ${app}.`
+                        : `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.` };
+            return { key, label, status: "warning", detail: `${state.route.file} exists but doesn't use ${handlerOf(state.route)} — ${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.`,
+                detail: state.route.router === "pages"
+                    ? `${state.route.file} calls ${pagesHandler}, but doctor can't see its default export always answer with the handler, and the default export is what answers ${who(state.listener)}. Export the handler as the default, or end the default function by returning its call, with no other return or throw.`
+                    : `${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 "router":
+            return {
+                key,
+                label,
+                status: "warning",
+                detail: `${who(state.listener)} comes from "@mapled/next/live/pages", the Pages Router's component, and ${state.dir}/ is the App Router's folder: it can't mount there (it needs next/router), so open tabs don't follow Publish. Import MapledLive from "@mapled/next/live" in the App Router.`,
+            };
+        case "pointer":
+            return {
+                key,
+                label,
+                status: "warning",
+                detail: `${state.route.file} ${state.route.handler === "GET" ? "answers with" : "calls"} ${pagesHandler}, which follows Mapled's live release: it moves the moment someone publishes, before the webhook refreshes what the App Router's pages read. ${who(state.listener)} ${runsIn(state.listener, facts) === "app" ? "runs" : "may run"} in the App Router and would refresh into a release those pages don't show yet. Mount ${handler} at ${routeFileFor(state.path, facts)} in its place — or, if only the Pages Router renders the listener, use <MapledLive /> from "@mapled/next/live/pages" in ${app}.`,
+            };
+        case "runtime":
+            return {
+                key,
+                label,
+                status: "warning",
+                detail: state.runtime === null
+                    ? `${state.route.file} may set runtime where doctor can't read it — Next reads it from export const runtime or export const config = { runtime }, written with literals. On the edge runtime ${pagesHandler} has no Node request and response to answer ${who(state.listener)} through: write runtime as "nodejs", or leave it out.`
+                    : `${state.route.file} sets runtime to ${JSON.stringify(state.runtime)} — ${pagesHandler} answers through Node's request and response, which an API route has only on the Node runtime, so ${who(state.listener)} gets an error there. Leave runtime out of the route, or set it to "nodejs".`,
             };
         case "unresolved":
             return {
@@ -504,7 +535,16 @@ export function checkLive(facts, framework) {
                 key,
                 label,
                 status: "warning",
-                detail: `${state.file} may set pageExtensions or basePath where doctor can't read them — 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.`,
+                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 {
@@ -513,6 +553,15 @@ export function checkLive(facts, framework) {
                 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,
@@ -527,7 +576,50 @@ export function checkLive(facts, framework) {
                 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 "missing":
+        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": {
+            if (state.pages) {
+                // the Pages Router: an API route, whose default export is the handler
+                const base = facts.basePath ?? "";
+                const file = state.endpoint === null ? null : pagesRouteFileFor(state.endpoint, facts);
+                return {
+                    key,
+                    label,
+                    status: "warning",
+                    detail: state.endpoint === null
+                        ? `${who(state.listener)} asks a release route the code doesn't have — export ${pagesHandler} as the default of an API route (${pagesRouteFileFor(RELEASE_ROUTE, facts)} by default).`
+                        : file !== null
+                            ? `${who(state.listener)} asks ${state.endpoint}, which has no route — export ${pagesHandler} as the default of ${file}.`
+                            : `${who(state.listener)} asks ${state.endpoint}, which has no route — and in the Pages Router only an API route answers it, at ${base}/api or under it. Point it at ${base}${RELEASE_ROUTE}, and export ${pagesHandler} as the default of ${pagesRouteFileFor(`${base}${RELEASE_ROUTE}`, facts)}.`,
+                };
+            }
             return state.endpoint === null
                 ? {
                     key,
@@ -541,6 +633,7 @@ export function checkLive(facts, framework) {
                     status: "warning",
                     detail: `${who(state.listener)} asks ${state.endpoint}, which has no route — mount ${handler} at ${routeFileFor(state.endpoint, facts)}.`,
                 };
+        }
     }
 }
 export function checkReads(lastReadAt) {

package/dist/live.d.ts

@@ -2,58 +2,110 @@
     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. */
+    `createReleaseHandler` from "@mapled/next/server". The Pages Router
+    has its own two: `<MapledLive />` from "@mapled/next/live/pages", and
+    an API route whose default export is `createPagesReleaseHandler`. 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;
+    /** `<MapledLive />` from "@mapled/next/live/pages": the Pages Router's
+        component, which only the Pages Router can mount (`next/router`) */
+    router?: "pages";
 };
-/** 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. */
+/** A route file and the path it answers: an App Router route handler
+    file, or a Pages Router API route (`router: "pages"`) — any file of the
+    pages folder whose path is /api or under it. `handler`: "GET" when the
+    tab's GET is seen to reach the release — the App Router route's
+    exported GET answers with `createReleaseHandler`, the API route's
+    default export with `createPagesReleaseHandler` — "other" when the file
+    calls that factory but its answer isn't seen to be the handler's (the
+    App Router handler exported as POST or not at all — the tab's GET gets
+    a 405 — or a GET or a default export that answers something else),
+    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). Both are the App Router's; an API route has
+    `runtime` instead: present when the file may run it on another runtime
+    than Node's — the runtime it writes out, or null where the reading
+    can't tell (pagesRuntime). */
 export type RouteFile = {
     file: string;
     path: string;
     handler: RouteHandler;
     params?: true;
+    segment?: SegmentSetting;
+    router?: "pages";
+    runtime?: string | null;
 };
 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. */
+/** A page file and the path it answers: an App Router `page.<ext>`, or a
+    Pages Router page (its API routes are route files). 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. */
+    site's page extension, `ts` by default. `appDir`, `pagesDir`: the App
+    Router and Pages Router folders Next reads, when the site has them.
+    `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;
+    pagesDir?: 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";
+};
+/** `missing`: `pages` when the listener runs in the Pages Router — the
+    route it lacks is an API route there. `router`: the Pages Router's
+    component in a file of the App Router folder `dir`, where it can't
+    mount. `pointer`: an API route answers with `createPagesReleaseHandler`
+    a listener the App Router may run (runsIn). `runtime`: the API route
+    that answers may run on another runtime than Node's. */
 export type LiveState = {
     kind: "unused";
     handlerRoute: RouteFile | null;
@@ -66,6 +118,21 @@ export type LiveState = {
     kind: "missing";
     listener: LiveListener;
     endpoint: string | null;
+    pages?: true;
+} | {
+    kind: "router";
+    listener: LiveListener;
+    dir: string;
+} | {
+    kind: "pointer";
+    listener: LiveListener;
+    route: RouteFile;
+    path: string;
+} | {
+    kind: "runtime";
+    listener: LiveListener;
+    route: RouteFile;
+    runtime: string | null;
 } | {
     kind: "unresolved";
     listener: LiveListener;
@@ -86,6 +153,24 @@ export type LiveState = {
     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;
@@ -96,6 +181,11 @@ export type LiveState = {
     listener: LiveListener;
     route: RouteFile;
     endpoint: string;
+} | {
+    kind: "segment";
+    listener: LiveListener;
+    route: RouteFile;
+    setting: SegmentSetting;
 };
 /** What the manifest records (§21.2). */
 export type Capabilities = {
@@ -104,17 +194,32 @@ export type Capabilities = {
 };
 /** 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): {
+/** The listeners one file mounts and, for a route file of `router`,
+    whether it serves the release: an App Router route through its GET, a
+    Pages API route through its default export. 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, router?: "app" | "pages"): {
     listeners: LiveListener[];
     handler: RouteHandler;
     params: boolean;
+    segment?: SegmentSetting;
+    runtime?: string | null;
 };
+/** 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
@@ -124,28 +229,83 @@ export declare function routeFileOf(file: string, extensions?: string[]): string
 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. */
+    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` and `basePath`, read only where the file
-    writes them out: a literal, once, directly in the object it exports —
-    `module.exports = {…}`, `export default nextConfig`, or passed to a
-    plugin: `withMDX(nextConfig)`. Null when it may set either anywhere
-    else: a value or a name the code builds (`["page" + "Extensions"]`, an
-    escaped identifier, `Object.assign`, `defineProperty`, a prototype
-    set by `setPrototypeOf` or `__proto__`, a member in a loop's head), an object from
-    another file or spread in, a member (`config.basePath = …`), a nested
-    object, any other mention — then no route can be checked. */
+/** 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;
+/** Which router runs a listener's code, as far as its file tells: a file
+    of the App Router folder is the App Router's; the Pages Router's
+    `<MapledLive />`, a file of the pages folder, or any file of a site
+    whose only router folder is the pages one — the Pages Router's. Null
+    for anything else: a file either router may render. */
+export declare function runsIn(listener: LiveListener, facts: LiveFacts): "app" | "pages" | null;
 /** Whether every listener has a route that answers it. The first one
-    that doesn't is the one to name. */
+    that doesn't is the one to name. An API route answers with the live
+    release (`createPagesReleaseHandler`), which moves the moment someone
+    publishes: it serves only listeners the Pages Router runs, whose pages
+    read that same release in getServerSideProps (README). A listener the
+    App Router may run refreshes on it before the webhook refreshes what
+    the App Router's pages read, into a release they don't show yet. */
 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. */
@@ -154,3 +314,9 @@ export declare function capabilitiesOf(state: LiveState): Capabilities;
     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;
+/** Where an API route answering `endpoint` goes, for a listener the Pages
+    Router runs: in the pages folder Next reads — without one, under
+    `src/pages` when the site keeps its code there — and without the
+    basePath. Null for a path no API route answers: Next serves them at
+    /api and under it only. */
+export declare function pagesRouteFileFor(endpoint: string, facts: LiveFacts): string | null;