@segmentstream/app 0.0.0-stage → 0.38.1

package/dist/navigation/build.js

@@ -0,0 +1,290 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, join, relative, resolve } from "node:path";
+import { navigationRoutesMayOverlap, parsePageCatalog } from "../navigation-protocol.js";
+import { generatePageCatalog, normalizePageRoute, pageCatalogCoverage, PageCatalogBuildError } from "./generate.js";
+import { PAGE_CATALOG_PLUGIN } from "./next.js";
+export * from "./generate.js";
+export { withPageCatalog } from "./next.js";
+export const PAGE_CATALOG_PATH = ".segmentstream/navigation/page-catalog.json";
+export const PAGE_CATALOG_CONTEXT_PATH = ".segmentstream/navigation/build-context.json";
+export const PAGE_CATALOG_COMPILED_PATH = ".segmentstream/navigation/compiled.json";
+function error(code, message) {
+    throw new PageCatalogBuildError(code, message);
+}
+function cleanupFailure(primary, cleanup) {
+    const message = primary instanceof Error ? primary.message : String(primary);
+    throw new AggregateError([primary, cleanup], `${message} (page catalog cleanup also failed).`, { cause: primary });
+}
+async function json(path) {
+    return JSON.parse(await readFile(path, "utf8"));
+}
+async function atomicJson(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, `${JSON.stringify(value)}\n`, { flag: "wx" });
+        await rename(temporary, path);
+    }
+    catch (cause) {
+        try {
+            await rm(temporary, { force: true });
+        }
+        catch (cleanup) {
+            cleanupFailure(cause, cleanup);
+        }
+        throw cause;
+    }
+}
+/** Read only routing source, never dependencies, generated artifacts, or page modules via import. */
+export async function readPageCatalogFiles(projectDir) {
+    const files = new Map();
+    async function walk(directory) {
+        let entries;
+        try {
+            entries = await readdir(directory, { withFileTypes: true });
+        }
+        catch (cause) {
+            if (cause.code === "ENOENT")
+                return;
+            throw cause;
+        }
+        for (const entry of entries) {
+            const path = join(directory, entry.name);
+            if (entry.isSymbolicLink())
+                error("unsupported_page_symlink", `Page catalog source must not contain symbolic links: ${relative(projectDir, path)}`);
+            if (entry.isDirectory())
+                await walk(path);
+            else if (entry.isFile())
+                files.set(relative(projectDir, path).split("\\").join("/"), await readFile(path, "utf8"));
+        }
+    }
+    for (const root of ["app", "src/app", "pages", "src/pages"])
+        await walk(join(projectDir, root));
+    for (const file of ["next.config.js", "next.config.mjs", "next.config.ts", "next.config.mts", "next.config.cjs"]) {
+        try {
+            files.set(file, await readFile(join(projectDir, file), "utf8"));
+        }
+        catch (cause) {
+            if (cause.code !== "ENOENT")
+                throw cause;
+        }
+    }
+    return files;
+}
+function fingerprint(files, routing) {
+    return createHash("sha256").update(JSON.stringify({ files: [...files].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0), routing })).digest("hex");
+}
+function routingFrom(config) {
+    return { basePath: config.basePath ?? "", trailingSlash: config.trailingSlash ?? false,
+        pageExtensions: config.pageExtensions ?? ["tsx", "ts", "jsx", "js"] };
+}
+function installedNext(projectDir) {
+    const require = createRequire(join(resolve(projectDir), "package.json"));
+    const version = require("next/package.json").version;
+    return { require, version };
+}
+function supportedNext(version) {
+    if (!/^16\.\d+\.\d+$/u.test(version))
+        error("unsupported_next_version", `Page discovery supports stable Next.js 16.x; found ${version}.`);
+}
+async function configuration(projectDir) {
+    const next = installedNext(projectDir);
+    const loader = next.require("next/dist/server/config.js");
+    const config = await loader.default("phase-production-build", resolve(projectDir));
+    return { ...next, config, enabled: Boolean(config.compiler?.runAfterProductionCompile &&
+            Reflect.get(config.compiler.runAfterProductionCompile, PAGE_CATALOG_PLUGIN) === true) };
+}
+/** Prove static matches exactly and compare complete path shapes for dynamic pages. */
+export function verifyPageCatalogRouting(catalog, inventory, frameworkInterceptions = []) {
+    const signature = (rule) => JSON.stringify([rule.source, rule.regex, rule.destination, rule.has, rule.missing]);
+    const interceptions = new Set(frameworkInterceptions.map(signature));
+    const earlyRules = [...inventory.redirects.filter((rule) => !rule.internal),
+        ...inventory.rewrites.beforeFiles.filter((rule) => !interceptions.has(signature(rule)))];
+    for (const page of catalog.pages) {
+        // Next checks afterFiles rewrites before its dynamic filesystem route table.
+        const rules = page.parameters.length === 0 ? earlyRules : [...earlyRules, ...inventory.rewrites.afterFiles];
+        for (const rule of rules) {
+            let overlaps;
+            if (page.parameters.length === 0)
+                overlaps = new RegExp(rule.regex, "i").test(page.route);
+            else {
+                overlaps = navigationRoutesMayOverlap(page.route, rule.source);
+            }
+            if (overlaps)
+                error("shadowed_page_route", `${page.ref}: a redirect or rewrite (${rule.source}) may intercept this page. Resolve its direct-load routing before advertising it.`);
+        }
+    }
+}
+async function configuredRouting(next) {
+    const load = next.require("next/dist/lib/load-custom-routes.js");
+    const build = next.require("next/dist/lib/build-custom-route.js");
+    const routes = await load.default(next.config);
+    return { redirects: routes.redirects.map((rule) => build.buildCustomRoute("redirect", rule, ["/_next"])),
+        rewrites: { beforeFiles: routes.rewrites.beforeFiles.map((rule) => build.buildCustomRoute("rewrite", rule)),
+            afterFiles: routes.rewrites.afterFiles, fallback: routes.rewrites.fallback } };
+}
+async function invalidate(projectDir) {
+    await Promise.all([PAGE_CATALOG_PATH, PAGE_CATALOG_CONTEXT_PATH, PAGE_CATALOG_COMPILED_PATH].map((path) => rm(join(projectDir, path), { force: true })));
+}
+async function invalidateAfterFailure(projectDir, primary) {
+    try {
+        await invalidate(projectDir);
+    }
+    catch (cleanup) {
+        cleanupFailure(primary, cleanup);
+    }
+    throw primary;
+}
+/** Run before parallel app/ontology builds, using the ontology evaluated from the same immutable source. */
+export async function preparePageCatalog(input) {
+    const projectDir = resolve(input.projectDir);
+    await invalidate(projectDir);
+    try {
+        const files = await readPageCatalogFiles(projectDir);
+        const next = await configuration(projectDir);
+        if (!next.enabled) {
+            if ([...files.keys()].some((file) => file.endsWith("/page.navigation.json"))) {
+                error("page_catalog_integration_required", "page.navigation.json requires withPageCatalog(nextConfig) from @segmentstream/app/navigation/next in next.config. Enable it before publishing page metadata.");
+            }
+            return { enabled: false, coverage: pageCatalogCoverage(files, routingFrom(next.config)) };
+        }
+        supportedNext(next.version);
+        if (!input.ontology || !Array.isArray(input.ontology.entities) || typeof input.ontology.hash !== "string") {
+            error("page_catalog_ontology_required", "Page discovery requires the ontology evaluated from this workspace source.");
+        }
+        const routing = routingFrom(next.config);
+        if (next.config.useFileSystemPublicRoutes === false || next.config.i18n) {
+            error("unsupported_routing_configuration", "Page discovery requires App Router filesystem routes without Pages Router i18n configuration.");
+        }
+        const catalog = generatePageCatalog({ files, routing, ontology: input.ontology, sourceHash: input.sourceHash });
+        verifyPageCatalogRouting(catalog, await configuredRouting(next));
+        const context = { version: 1, ontology: { hash: input.ontology.hash,
+                entities: input.ontology.entities.map(({ name }) => ({ name })) }, sourceHash: input.sourceHash, routing,
+            sourceFingerprint: fingerprint(files, routing), distDir: next.config.distDir, nextVersion: next.version };
+        await atomicJson(join(projectDir, PAGE_CATALOG_CONTEXT_PATH), context);
+        await atomicJson(join(projectDir, PAGE_CATALOG_PATH), catalog);
+        return { enabled: true, catalog, catalogPath: join(projectDir, PAGE_CATALOG_PATH), coverage: pageCatalogCoverage(files, routing) };
+    }
+    catch (cause) {
+        return invalidateAfterFailure(projectDir, cause);
+    }
+}
+async function prepared(projectDir, routing) {
+    let context;
+    let catalog;
+    try {
+        context = await json(join(projectDir, PAGE_CATALOG_CONTEXT_PATH));
+        catalog = parsePageCatalog(await json(join(projectDir, PAGE_CATALOG_PATH)));
+    }
+    catch (cause) {
+        throw new PageCatalogBuildError("page_catalog_not_prepared", "Page discovery is enabled but its prepared catalog is missing or invalid. Run segmentstream-page-catalog generate with the evaluated ontology and immutable source identity before building.", { cause });
+    }
+    if (context.version !== 1)
+        error("page_catalog_not_prepared", "Unsupported page catalog preparation context; regenerate it.");
+    const files = await readPageCatalogFiles(projectDir);
+    if (fingerprint(files, routing ?? context.routing) !== context.sourceFingerprint) {
+        error("page_catalog_source_mismatch", "App routing or source changed after page catalog preparation; regenerate from the build's immutable source.");
+    }
+    const regenerated = generatePageCatalog({ files, routing: context.routing, ontology: context.ontology, sourceHash: context.sourceHash });
+    if (JSON.stringify(regenerated) !== JSON.stringify(catalog))
+        error("page_catalog_source_mismatch", "Prepared page catalog differs from the current source; regenerate it.");
+    return { context, catalog, files };
+}
+function verifyCompiledRoutes(catalog, manifest, routing) {
+    // Compiled keys have already decoded escaped private prefixes; they are not filesystem paths.
+    const direct = Object.keys(manifest).filter((path) => path.endsWith("/page") &&
+        !path.includes("/@") && !/\/\(\.{1,3}\)/u.test(path)).map((path) => {
+        const pathname = `/${path.split("/").filter(Boolean).slice(0, -1)
+            .filter((segment) => !(segment.startsWith("(") && segment.endsWith(")"))).join("/")}`.replace(/%5F/g, "_");
+        return normalizePageRoute(pathname, routing);
+    });
+    for (const page of catalog.pages) {
+        if (!direct.includes(page.route))
+            error("page_catalog_route_mismatch", `${page.ref}: no direct-load UI page exists in Next's compiled app route inventory.`);
+    }
+}
+/** Compiler-stage safety check; final verification below must also follow the complete build command. */
+export async function verifyCompiledPageCatalog(input) {
+    try {
+        const { context, catalog } = await prepared(input.projectDir, input.routing === undefined ? undefined : routingFrom(input.routing));
+        const next = installedNext(input.projectDir);
+        supportedNext(next.version);
+        if (context.nextVersion !== next.version)
+            error("page_catalog_source_mismatch", "The installed Next.js version changed after catalog preparation.");
+        const manifest = await readFile(join(input.distDir, "server/app-paths-manifest.json"), "utf8");
+        verifyCompiledRoutes(catalog, JSON.parse(manifest), context.routing);
+        await atomicJson(join(input.projectDir, PAGE_CATALOG_COMPILED_PATH), { revision: catalog.revision,
+            manifestHash: createHash("sha256").update(manifest).digest("hex") });
+    }
+    catch (cause) {
+        return invalidateAfterFailure(input.projectDir, cause);
+    }
+}
+/** Verify final resolved routes after any app build command, including custom commands. */
+export async function verifyPageCatalogBuild(input) {
+    const projectDir = resolve(input.projectDir);
+    try {
+        const next = await configuration(projectDir);
+        if (!next.enabled) {
+            const files = await readPageCatalogFiles(projectDir);
+            let wasPrepared = false;
+            try {
+                await readFile(join(projectDir, PAGE_CATALOG_CONTEXT_PATH));
+                wasPrepared = true;
+            }
+            catch (cause) {
+                if (cause.code !== "ENOENT")
+                    throw cause;
+            }
+            if (wasPrepared)
+                error("page_catalog_integration_required", "The prepared catalog requires withPageCatalog in the final build configuration, including an enabled empty catalog.");
+            if ([...files.keys()].some((file) => file.endsWith("/page.navigation.json"))) {
+                error("page_catalog_integration_required", "Page metadata requires withPageCatalog(nextConfig) before it can be published.");
+            }
+            return { enabled: false };
+        }
+        supportedNext(next.version);
+        const { context, catalog } = await prepared(projectDir, routingFrom(next.config));
+        if (context.distDir !== next.config.distDir || context.nextVersion !== next.version)
+            error("page_catalog_source_mismatch", "Next.js build configuration changed after catalog preparation.");
+        const distDir = resolve(projectDir, context.distDir);
+        if (!(await readFile(join(distDir, "BUILD_ID"), "utf8")).trim())
+            error("page_catalog_build_incomplete", "Next.js build did not complete.");
+        const compiledSource = await readFile(join(distDir, "server/app-paths-manifest.json"), "utf8");
+        const compiled = JSON.parse(compiledSource);
+        const proof = await json(join(projectDir, PAGE_CATALOG_COMPILED_PATH));
+        if (proof.revision !== catalog.revision || proof.manifestHash !== createHash("sha256").update(compiledSource).digest("hex")) {
+            error("page_catalog_build_incomplete", "The current Next.js build did not verify the prepared page catalog; run the complete app build command.");
+        }
+        verifyCompiledRoutes(catalog, compiled, context.routing);
+        const resolvedRoutes = await json(join(distDir, "app-path-routes-manifest.json"));
+        const manifest = await json(join(distDir, "routes-manifest.json"));
+        const required = await json(join(distDir, "required-server-files.json"));
+        if (Reflect.get(required.config.experimental ?? {}, "isExperimentalCompile") === true) {
+            error("page_catalog_build_incomplete", "A compile-only Next.js build must finish generation before final page catalog verification.");
+        }
+        if (manifest.version !== 3 || manifest.basePath !== context.routing.basePath ||
+            JSON.stringify(routingFrom(required.config)) !== JSON.stringify(context.routing)) {
+            error("page_catalog_route_mismatch", "Final Next.js routing configuration does not match the prepared page catalog.");
+        }
+        for (const page of catalog.pages) {
+            const resolvedPage = Object.entries(resolvedRoutes).some(([appPath, pathname]) => appPath.endsWith("/page") && !appPath.includes("/@") && !/\/\(\.{1,3}\)/u.test(appPath) &&
+                normalizePageRoute(pathname.replace(/%5F/g, "_"), context.routing) === page.route && Object.hasOwn(compiled, appPath));
+            const served = [...manifest.staticRoutes, ...manifest.dynamicRoutes].some((route) => normalizePageRoute(route.page, context.routing) === page.route);
+            if (!resolvedPage || !served)
+                error("page_catalog_route_mismatch", `${page.ref}: the final Next.js route inventory does not serve this UI page.`);
+        }
+        // Reconstruct only Next's own context-dependent interception rules from its resolved inventory.
+        // A direct page stays addressable while an unannotated modal variant handles client navigation.
+        const interceptionAdapter = next.require("next/dist/lib/generate-interception-routes-rewrites.js");
+        const customRouteAdapter = next.require("next/dist/lib/build-custom-route.js");
+        const interceptions = interceptionAdapter.generateInterceptionRoutesRewrites([...new Set(Object.values(resolvedRoutes))], context.routing.basePath ?? "").map((rule) => customRouteAdapter.buildCustomRoute("rewrite", rule));
+        verifyPageCatalogRouting(catalog, manifest, interceptions);
+        return { enabled: true, revision: catalog.revision, pages: catalog.pages.length };
+    }
+    catch (cause) {
+        return invalidateAfterFailure(projectDir, cause);
+    }
+}

package/dist/navigation/cli.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+export declare function runPageCatalogCommand(args: readonly string[]): Promise<{
+    enabled: false;
+    revision?: undefined;
+    pages?: undefined;
+} | {
+    enabled: true;
+    revision: string;
+    pages: number;
+} | {
+    catalogPath?: string | undefined;
+    revision?: string | undefined;
+    enabled: boolean;
+    coverage: {
+        pages: number;
+        annotated: number;
+        unannotated: number;
+    };
+}>;

package/dist/navigation/cli.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { realpathSync, writeSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { preparePageCatalog, verifyPageCatalogBuild } from "./build.js";
+export async function runPageCatalogCommand(args) {
+    const [command, ...options] = args;
+    const values = new Map();
+    for (let index = 0; index < options.length; index += 2) {
+        const key = options[index];
+        const value = options[index + 1];
+        if (!["--project-dir", "--ontology", "--source-hash"].includes(key) || !value || values.has(key)) {
+            throw new Error("Usage: segmentstream-page-catalog generate --project-dir <app> --ontology <manifest.json> --source-hash <identity> | verify --project-dir <app>");
+        }
+        values.set(key, value);
+    }
+    const projectDir = values.get("--project-dir");
+    if (!projectDir)
+        throw new Error("--project-dir is required.");
+    if (command === "verify" && values.size === 1)
+        return verifyPageCatalogBuild({ projectDir });
+    if (command !== "generate" || !values.has("--ontology") || !values.has("--source-hash")) {
+        throw new Error("generate requires --ontology and --source-hash; verify accepts only --project-dir.");
+    }
+    const ontology = JSON.parse(await readFile(values.get("--ontology"), "utf8"));
+    const result = await preparePageCatalog({ projectDir, ontology, sourceHash: values.get("--source-hash") });
+    return { enabled: result.enabled, coverage: result.coverage,
+        ...(result.enabled ? { catalogPath: result.catalogPath, revision: result.catalog.revision } : {}) };
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+    runPageCatalogCommand(process.argv.slice(2)).then((result) => {
+        writeSync(1, `${JSON.stringify(result)}\n`);
+    }).catch((cause) => {
+        writeSync(2, `${cause instanceof Error ? cause.message : String(cause)}\n`);
+        process.exitCode = 1;
+    });
+}

package/dist/navigation/generate.d.ts

@@ -0,0 +1,43 @@
+import { type PageCatalogV1 } from "../navigation-protocol.js";
+export { NavigationCatalogError, parsePageCatalog } from "../navigation-protocol.js";
+export type { PageCatalogV1, PageEntry, PageMetadata } from "../navigation-protocol.js";
+export declare class PageCatalogBuildError extends Error {
+    readonly code: string;
+    readonly name = "PageCatalogBuildError";
+    constructor(code: string, message: string, options?: ErrorOptions);
+}
+export interface PageCatalogRouting {
+    readonly basePath?: string;
+    readonly trailingSlash?: boolean;
+    readonly pageExtensions?: readonly string[];
+}
+export interface PageCatalogOntology {
+    readonly hash: string;
+    readonly entities: readonly {
+        readonly name: string;
+    }[];
+}
+export interface GeneratePageCatalogInput {
+    readonly files: ReadonlyMap<string, string>;
+    readonly routing?: PageCatalogRouting;
+    readonly ontology: PageCatalogOntology;
+    readonly sourceHash: string;
+}
+export interface PageRoute {
+    readonly file: string;
+    readonly appPath: string;
+    readonly pathname: string;
+    readonly route: string;
+    readonly parallel: boolean;
+    readonly intercepted: boolean;
+}
+export declare function normalizePageRoute(pathname: string, routing?: PageCatalogRouting): string;
+/** Extract App Router page files without importing or executing page components. */
+export declare function extractPageRoutes(files: ReadonlyMap<string, string>, routing?: PageCatalogRouting): readonly PageRoute[];
+/** Pure, deterministic Node build-time compiler. Source strings are never executed. */
+export declare function generatePageCatalog(input: GeneratePageCatalogInput): PageCatalogV1;
+export declare function pageCatalogCoverage(files: ReadonlyMap<string, string>, routing?: PageCatalogRouting): {
+    pages: number;
+    annotated: number;
+    unannotated: number;
+};

package/dist/navigation/generate.js

@@ -0,0 +1,138 @@
+import { createPageCatalog, NavigationCatalogError } from "../navigation-protocol.js";
+export { NavigationCatalogError, parsePageCatalog } from "../navigation-protocol.js";
+export class PageCatalogBuildError extends Error {
+    code;
+    name = "PageCatalogBuildError";
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+function fail(code, message) {
+    throw new PageCatalogBuildError(code, message);
+}
+export function normalizePageRoute(pathname, routing = {}) {
+    const basePath = routing.basePath ?? "";
+    if (basePath !== "" && (!basePath.startsWith("/") || basePath.endsWith("/") ||
+        /[?#\\\s\[\]]/u.test(basePath) || basePath.includes("//"))) {
+        fail("unsupported_routing_configuration", "basePath must be an absolute static path without a trailing slash.");
+    }
+    const route = `${basePath}${pathname === "/" ? "" : pathname}` || "/";
+    // Next leaves file-like paths and root .well-known paths without an appended slash.
+    const slashException = pathname !== "/" && (/\/[^/[\]]*\.[^/[\]]*$/u.test(route) || /^\/\.well-known(?:\/|$)/iu.test(route));
+    return routing.trailingSlash && !slashException && !route.endsWith("/") ? `${route}/` : route;
+}
+/** Extract App Router page files without importing or executing page components. */
+export function extractPageRoutes(files, routing = {}) {
+    const paths = [...files.keys()].sort();
+    for (const file of paths) {
+        if (file.startsWith("/") || file.includes("\\") || file.split("/").some((part) => part === "." || part === "..")) {
+            fail("invalid_source_path", `Expected an app-root relative POSIX file path: ${file}`);
+        }
+    }
+    const root = paths.some((file) => file.startsWith("app/")) ? "app/" : "src/app/";
+    const extensions = routing.pageExtensions ?? ["tsx", "ts", "jsx", "js"];
+    if (extensions.length === 0 || extensions.some((extension) => !/^[a-zA-Z0-9][a-zA-Z0-9.-]*$/u.test(extension))) {
+        fail("unsupported_routing_configuration", "pageExtensions must contain supported file extensions.");
+    }
+    const routes = [];
+    for (const file of paths) {
+        if (!file.startsWith(root) || !extensions.some((extension) => file.endsWith(`/page.${extension}`)))
+            continue;
+        const segments = file.slice(root.length).split("/").slice(0, -1);
+        if (segments.some((segment) => segment.startsWith("_")))
+            continue;
+        const intercepted = segments.some((segment) => /^\(\.{1,3}\)/u.test(segment));
+        const visible = segments.filter((segment) => !segment.startsWith("@") && !(segment.startsWith("(") && segment.endsWith(")")));
+        const pathname = `/${visible.join("/")}`.replace(/%5F/g, "_");
+        routes.push({ file, appPath: `/${[...segments, "page"].join("/")}`, pathname,
+            route: normalizePageRoute(pathname, routing), parallel: segments.some((segment) => segment.startsWith("@")), intercepted });
+    }
+    return routes;
+}
+function metadata(source, file) {
+    let value;
+    try {
+        value = JSON.parse(source);
+    }
+    catch (cause) {
+        throw new PageCatalogBuildError("invalid_page_metadata", `${file}: invalid JSON.`, { cause });
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value) ||
+        Object.keys(value).some((key) => !["title", "description", "entities", "parameters", "query"].includes(key))) {
+        fail("invalid_page_metadata", `${file}: expected page metadata with title, description, entities and optional hints; routes are generated.`);
+    }
+    const data = value;
+    for (const key of ["parameters", "query"]) {
+        if (data[key] !== undefined && (typeof data[key] !== "object" || data[key] === null || Array.isArray(data[key]))) {
+            fail("invalid_page_metadata", `${file}: ${key} must be a hint map.`);
+        }
+    }
+    // Field values and all wire limits are validated by the canonical ontology contract.
+    return value;
+}
+function parameters(pathname, hints, file) {
+    const result = [];
+    for (const segment of pathname.split("/")) {
+        const match = /^(?:\[\[\.\.\.([^\[\]]+)\]\]|\[\.\.\.([^\[\]]+)\]|\[([^\[\]]+)\])$/u.exec(segment);
+        if (!match)
+            continue;
+        const name = match[1] ?? match[2] ?? match[3];
+        result.push({ name, kind: match[3] === undefined ? "catch_all" : "segment", required: match[1] === undefined,
+            ...(hints && Object.hasOwn(hints, name) ? { description: hints[name] } : {}) });
+    }
+    for (const name of Object.keys(hints ?? {})) {
+        if (!result.some((parameter) => parameter.name === name)) {
+            fail("unknown_page_parameter", `${file}: parameter hint ${JSON.stringify(name)} does not name a route parameter.`);
+        }
+    }
+    return result;
+}
+/** Pure, deterministic Node build-time compiler. Source strings are never executed. */
+export function generatePageCatalog(input) {
+    const routes = extractPageRoutes(input.files, input.routing);
+    const entities = new Set(input.ontology.entities.map((entity) => entity.name));
+    const pages = [];
+    for (const [file, source] of [...input.files].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
+        if (!file.endsWith("/page.navigation.json"))
+            continue;
+        const directory = file.slice(0, -"page.navigation.json".length);
+        const matches = routes.filter((route) => route.file.slice(0, route.file.lastIndexOf("/") + 1) === directory);
+        if (matches.length === 0)
+            fail("orphan_page_metadata", `${file}: no routable page exists beside this annotation under the active App Router root and pageExtensions.`);
+        if (matches.length > 1)
+            fail("duplicate_page_route", `${file}: more than one configured page file exists beside this annotation.`);
+        const route = matches[0];
+        if (route.intercepted)
+            fail("unsupported_intercepted_page", `${file}: intercepted UI has no independent direct-load URL; annotate its ordinary destination or containing page.`);
+        if (route.parallel && !routes.some((other) => !other.parallel && !other.intercepted && other.pathname === route.pathname)) {
+            fail("unsupported_parallel_page", `${file}: no ordinary direct-load page establishes this parallel variant's URL; annotate its containing page.`);
+        }
+        const data = metadata(source, file);
+        const entry = { ref: `page:${route.route}`, route: route.route, title: data.title,
+            description: data.description, entities: data.entities, parameters: parameters(route.pathname, data.parameters, file),
+            query: data.query ?? {} };
+        // Delegate wire validation to the canonical contract before checking references.
+        let normalized;
+        try {
+            normalized = createPageCatalog([entry], { ontologyHash: input.ontology.hash, sourceHash: input.sourceHash }).pages[0];
+        }
+        catch (cause) {
+            if (cause instanceof NavigationCatalogError) {
+                throw new PageCatalogBuildError(cause.code, `${file}: ${cause.message}`, { cause });
+            }
+            throw cause;
+        }
+        for (const name of normalized.entities) {
+            if (!entities.has(name))
+                fail("unknown_page_entity", `${file}: unknown ontology entity ${JSON.stringify(name)}.`);
+        }
+        pages.push(normalized);
+    }
+    return createPageCatalog(pages, { ontologyHash: input.ontology.hash, sourceHash: input.sourceHash });
+}
+export function pageCatalogCoverage(files, routing) {
+    const routes = extractPageRoutes(files, routing).filter((route) => !route.parallel && !route.intercepted);
+    const annotated = routes.filter((route) => files.has(`${route.file.slice(0, route.file.lastIndexOf("/") + 1)}page.navigation.json`));
+    return { pages: routes.length, annotated: annotated.length, unannotated: routes.length - annotated.length };
+}

package/dist/navigation/next.d.ts

@@ -0,0 +1,10 @@
+import type { NextConfig } from "next";
+export declare const PAGE_CATALOG_PLUGIN: unique symbol;
+type ConfigFunction = (phase: string, context: {
+    defaultConfig: NextConfig;
+}) => NextConfig | Promise<NextConfig>;
+/** Opt into page discovery without changing page components or replacing other Next plugins. */
+export declare function withPageCatalog(config: NextConfig): NextConfig;
+export declare function withPageCatalog(config: ConfigFunction): ConfigFunction;
+export declare function withPageCatalog(config: Promise<NextConfig>): Promise<NextConfig>;
+export {};

package/dist/navigation/next.js

@@ -0,0 +1,18 @@
+import { verifyCompiledPageCatalog } from "./build.js";
+export const PAGE_CATALOG_PLUGIN = Symbol.for("@segmentstream/app/page-catalog");
+export function withPageCatalog(config) {
+    if (typeof config === "function") {
+        return async (phase, context) => withPageCatalog(await config(phase, context));
+    }
+    if ("then" in config)
+        return Promise.resolve(config).then((resolved) => withPageCatalog(resolved));
+    const previous = config.compiler?.runAfterProductionCompile;
+    if (previous && Reflect.get(previous, PAGE_CATALOG_PLUGIN) === true)
+        return config;
+    const runAfterProductionCompile = async (metadata) => {
+        await previous?.(metadata);
+        await verifyCompiledPageCatalog({ projectDir: metadata.projectDir, distDir: metadata.distDir });
+    };
+    Object.defineProperty(runAfterProductionCompile, PAGE_CATALOG_PLUGIN, { value: true });
+    return { ...config, compiler: { ...config.compiler, runAfterProductionCompile } };
+}

package/dist/navigation-protocol.d.ts

@@ -0,0 +1,55 @@
+/** Workspace-authored metadata beside an ordinary UI page. Routes are generated, never authored. */
+export interface PageMetadata {
+    readonly title: string;
+    readonly entities: readonly string[];
+    readonly description: string;
+    readonly parameters?: Readonly<Record<string, string>>;
+    readonly query?: Readonly<Record<string, string>>;
+}
+export interface PageEntry {
+    readonly ref: string;
+    readonly route: string;
+    readonly title: string;
+    readonly description: string;
+    readonly entities: readonly string[];
+    readonly parameters: readonly {
+        readonly name: string;
+        readonly kind: "segment" | "catch_all";
+        readonly required: boolean;
+        readonly description?: string;
+    }[];
+    readonly query: Readonly<Record<string, string>>;
+}
+export interface PageCatalogV1 {
+    readonly version: 1;
+    readonly revision: string;
+    readonly pages: readonly PageEntry[];
+}
+export declare const NAVIGATION_CATALOG_LIMITS: Readonly<{
+    pages: 1000;
+    bytes: number;
+    title: 120;
+    description: 2000;
+    hint: 512;
+    associations: 32;
+    hints: 32;
+    responseBytes: number;
+}>;
+/**
+ * Whether a generated page and a routing source can share a path. Compare complete segment
+ * shapes for ordinary parameters, optional parameters and catch-alls; custom regex sources
+ * remain conservative when their static prefixes cannot prove disjointness.
+ */
+export declare function navigationRoutesMayOverlap(route: string, source: string): boolean;
+export declare class NavigationCatalogError extends Error {
+    readonly code: "invalid_page_catalog" | "page_catalog_too_large";
+    readonly name = "NavigationCatalogError";
+    constructor(code: "invalid_page_catalog" | "page_catalog_too_large", message: string);
+}
+/** Validate and copy an untrusted artifact. Entity existence is checked against the serving ontology. */
+export declare function parsePageCatalog(value: unknown): PageCatalogV1;
+/** Generate an immutable catalog identity from normalized metadata, ontology, and source identity. */
+export declare function createPageCatalog(pages: readonly PageEntry[], context: {
+    readonly ontologyHash: string;
+    readonly sourceHash: string;
+}): PageCatalogV1;