@warlock.js/web 5.0.0

package/esm/build/discover-pages.mjs

@@ -0,0 +1,294 @@
+import { composeRoutePath } from "../routing/compose-route-path.mjs";
+import { NestedLayoutsNotSupportedError, selectPageLayout } from "../routing/layout-policy.mjs";
+import { deriveFallbackRouteName } from "../routing/route-identity.mjs";
+import { NonLiteralRouteExportError, readRouteExports } from "./read-route-exports.mjs";
+import fs from "node:fs";
+import path from "node:path";
+import { parse } from "@babel/parser";
+
+//#region ../web/src/build/discover-pages.ts
+/**
+* Static discovery of the application's page graph — the ONE scan every
+* provider shares.
+*
+* This module has a single responsibility: look at the filesystem and produce
+* the recipe. It writes nothing, knows nothing about the generated barrel, and
+* imports neither Vite nor a single application module. Everything that turns
+* the recipe into an artefact (the production barrel, the dev plugin, the
+* generated client entry) lives with that artefact and consumes
+* {@link discoverPages}.
+*
+* The reason it is one module rather than one function per consumer: two
+* scanners that agree today drift tomorrow, and a page that exists for the
+* server but not the client is the silent failure that costs a day to find.
+* Sharing the scan makes that disagreement impossible by construction instead
+* of catchable by test.
+*
+* "Static" means WITHOUT RUNNING THE APPLICATION — this module globs
+* `*.page.tsx`, `layout.tsx` and `root.tsx`, and reads each page's declared
+* `route` and each layout's declared `prefix` by PARSING the source
+* ({@link readRouteExports}). It still imports no application module.
+*
+* The route a page is served under is the one the page DECLARES, not the one
+* its directory suggests, so that is the route discovery reports. The
+* composition — EVERY layout `prefix` on the page's path, outermost first, plus
+* the page's own `route` path — and the fallback used when a route omits its
+* name are mirrored from the server's installer (`installPageRoutes`),
+* deliberately and in one direction: build and boot agree because one of them
+* copies the other, not because two conventions were written to match.
+*
+* Discovery also CLASSIFIES each layout — does its module have a default
+* export, does it export `middleware` — because the layout policy
+* ({@link "../routing/layout-policy.ts"}) owns the rule but may not touch a
+* filesystem to learn the facts the rule needs. That classification is another
+* parse, never an import: a layout is read exactly the way a page's `route` is.
+*/
+/** Raised when two pages claim one route name. */
+var DuplicatePageRouteNameError = class extends Error {
+	routeName;
+	firstFile;
+	secondFile;
+	constructor(routeName, firstFile, secondFile) {
+		super(`Two pages resolve to the same route name "${routeName}": "${firstFile}" and "${secondFile}". A route name identifies exactly one page, so the second page would be unreachable. To fix: rename one of the files, or move it so its directory gives it a different route name.`);
+		this.routeName = routeName;
+		this.firstFile = firstFile;
+		this.secondFile = secondFile;
+		this.name = "DuplicatePageRouteNameError";
+	}
+};
+function toPosix(value) {
+	return value.replace(/\\/g, "/");
+}
+function isDirectory(candidate) {
+	try {
+		return fs.statSync(candidate).isDirectory();
+	} catch {
+		return false;
+	}
+}
+function isFile(candidate) {
+	try {
+		return fs.statSync(candidate).isFile();
+	} catch {
+		return false;
+	}
+}
+/**
+* The two page roots: the global `src/web/**` tree and each
+* module's `src/app/<module>/web/**` tree. Both are optional; a project with
+* neither has zero pages, which is a legal empty state.
+*/
+function discoverWebRoots(srcRoot) {
+	const roots = [];
+	const globalRoot = path.join(srcRoot, "web");
+	if (isDirectory(globalRoot)) roots.push(globalRoot);
+	const appDir = path.join(srcRoot, "app");
+	if (isDirectory(appDir)) for (const entry of fs.readdirSync(appDir, { withFileTypes: true }).sort(byName)) {
+		if (!entry.isDirectory()) continue;
+		const moduleWebRoot = path.join(appDir, entry.name, "web");
+		if (isDirectory(moduleWebRoot)) roots.push(moduleWebRoot);
+	}
+	return roots;
+}
+function byName(left, right) {
+	return left.name < right.name ? -1 : left.name > right.name ? 1 : 0;
+}
+/** Every file under `dir` (recursive) whose name matches `predicate`. */
+function walkFiles(dir, predicate) {
+	const found = [];
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort(byName)) {
+		const full = path.join(dir, entry.name);
+		if (entry.isDirectory()) found.push(...walkFiles(full, predicate));
+		else if (entry.isFile() && predicate(entry.name)) found.push(full);
+	}
+	return found;
+}
+/**
+* A page's layout chain: every `layout.tsx` in the directories from its web
+* root down to its own directory, OUTERMOST FIRST.
+*
+* Dev's installer reads only the nearest layout today, because its page module
+* triple holds a single layout; the recipe carries the whole chain so the
+* runtime side can compose
+* nested layouts without a second discovery pass. The nearest layout is always
+* the LAST element, so a consumer that still wants dev's one-layout behaviour
+* reads `layouts.at(-1)`.
+*/
+function layoutChainFor(pageFile, webRoot) {
+	const chain = [];
+	const relativeDir = path.relative(webRoot, path.dirname(pageFile));
+	const segments = relativeDir === "" ? [] : relativeDir.split(path.sep);
+	let current = webRoot;
+	for (let index = 0; index <= segments.length; index++) {
+		if (index > 0) current = path.join(current, segments[index - 1]);
+		const candidate = path.join(current, "layout.tsx");
+		if (isFile(candidate)) chain.push(candidate);
+	}
+	return chain;
+}
+function compareStrings(left, right) {
+	return left < right ? -1 : left > right ? 1 : 0;
+}
+/**
+* The total order every consumer sees, and the reason discovery returns an
+* array rather than a set: the page's SOURCE FILE PATH, lexicographic, POSIX.
+*
+* Serialization order only; matching precedence is a property of the route
+* grammar, not of this array.
+*
+* The file path rather than the route path, now that the route is the declared
+* one: a page's route can be rewritten by editing one line, which would reorder
+* an artefact that has not otherwise changed, while the file it lives in is the
+* stable identity the artefact is built from. It also carries no suggestion of
+* precedence — nobody reads "sorted by file name" as "most specific first",
+* which is the misreading a route-path order invites.
+*
+* Lexicographic because it is byte-comparable output across every provider,
+* which keeps diffs stable and keeps filesystem enumeration order out of the
+* artefact: two machines that list a directory differently must still produce
+* byte-identical output, or a build is only reproducible by luck.
+*/
+function comparePages(left, right) {
+	return compareStrings(toPosix(left.pageFile), toPosix(right.pageFile));
+}
+function assertUniqueRouteNames(pages, appRoot) {
+	const fileByRouteName = /* @__PURE__ */ new Map();
+	for (const page of pages) {
+		const existing = fileByRouteName.get(page.routeName);
+		const relative = toPosix(path.relative(appRoot, page.pageFile));
+		if (existing !== void 0) throw new DuplicatePageRouteNameError(page.routeName, existing, relative);
+		fileByRouteName.set(page.routeName, relative);
+	}
+}
+/** Raised when a `*.page.tsx` declares no `route` export. */
+var MissingRouteExportError = class extends Error {
+	pageFile;
+	constructor(pageFile) {
+		super(`"${pageFile}" is a page file but declares no \`route\` export. A page with no route is a page the dev server would still serve and production would 404 on, so the build refuses it instead. For example: export const route = "/list";`);
+		this.pageFile = pageFile;
+		this.name = "MissingRouteExportError";
+	}
+};
+/**
+* The declared exports of one file, or a thrown
+* {@link NonLiteralRouteExportError} when they cannot be read without running
+* the application. Layouts are read once per run and remembered: a layout is
+* the nearest one for every page beside it, and parsing it once per page would
+* be the same answer bought repeatedly.
+*/
+function readDeclarations(sourceFile, cache) {
+	let result = cache.get(sourceFile);
+	if (result === void 0) {
+		result = readRouteExports(sourceFile);
+		cache.set(sourceFile, result);
+	}
+	if (!result.ok) throw new NonLiteralRouteExportError(result.rejection);
+	return result;
+}
+/**
+* Parses one layout and reports its shape. Remembered per run for the same
+* reason declarations are: a layout is on the path of every page beneath it.
+*/
+function readLayoutShape(layoutFile, cache) {
+	const cached = cache.get(layoutFile);
+	if (cached !== void 0) return cached;
+	const source = fs.readFileSync(layoutFile, "utf-8");
+	let program;
+	try {
+		program = parse(source, {
+			sourceType: "module",
+			plugins: ["typescript", "jsx"],
+			errorRecovery: false
+		}).program;
+	} catch (error) {
+		throw new Error(`Cannot read the exports of "${layoutFile}": the file could not be parsed (${error.message}). Fix the syntax error and the build will continue.`);
+	}
+	const shape = {
+		renders: false,
+		hasMiddleware: false
+	};
+	for (const statement of program.body) {
+		if (statement.type === "ExportDefaultDeclaration") {
+			shape.renders = true;
+			continue;
+		}
+		if (statement.type === "ExportAllDeclaration") {
+			shape.hasMiddleware = true;
+			continue;
+		}
+		if (statement.type !== "ExportNamedDeclaration" || statement.exportKind === "type") continue;
+		for (const specifier of statement.specifiers) {
+			if (specifier.type !== "ExportSpecifier" || specifier.exportKind === "type") continue;
+			const exported = specifier.exported.type === "Identifier" ? specifier.exported.name : specifier.exported.value;
+			if (exported === "default") shape.renders = true;
+			if (exported === "middleware") shape.hasMiddleware = true;
+		}
+		const { declaration } = statement;
+		if (declaration === null || declaration === void 0) continue;
+		if (declaration.type === "VariableDeclaration") {
+			for (const declarator of declaration.declarations) if (declarator.id.type === "Identifier" && declarator.id.name === "middleware") shape.hasMiddleware = true;
+			continue;
+		}
+		if ((declaration.type === "FunctionDeclaration" || declaration.type === "ClassDeclaration") && declaration.id?.name === "middleware") shape.hasMiddleware = true;
+	}
+	cache.set(layoutFile, shape);
+	return shape;
+}
+/**
+* Scans both web roots and returns the pages in a defined total order.
+*
+* Zero pages is a legal result, not an error: a project may be configured
+* with web and have nothing to serve yet. What is an error is a `*.page.tsx`
+* with no `route` export, which is refused rather than silently omitted — an
+* artefact that leaves a page out is a page the dev server still serves and
+* production 404s on; two pages claiming one route name, which this refuses
+* to return at all — the alternative is an artefact in which one of them is
+* silently unreachable; a `route` or `prefix` that cannot be read without
+* running the application, which is refused before any page is reported at
+* all; and a page whose layout chain holds more than one RENDERING layout, which
+* the production installer would refuse anyway — discovery refuses it first so
+* that artefact is never produced.
+*/
+function discoverPages(options) {
+	const { appRoot } = options;
+	const srcRoot = path.join(appRoot, options.srcDir ?? "src");
+	const webRoots = discoverWebRoots(srcRoot);
+	const appFile = path.join(srcRoot, "web", "root.tsx");
+	const hasAppFile = isFile(appFile);
+	const declarations = /* @__PURE__ */ new Map();
+	const layoutShapes = /* @__PURE__ */ new Map();
+	const relativeToApp = (file) => toPosix(path.relative(appRoot, file));
+	const pages = [];
+	for (const webRoot of webRoots) for (const pageFile of walkFiles(webRoot, (fileName) => fileName.endsWith(".page.tsx"))) {
+		const { route } = readDeclarations(pageFile, declarations);
+		if (route === void 0) throw new MissingRouteExportError(relativeToApp(pageFile));
+		const layouts = layoutChainFor(pageFile, webRoot);
+		const shapes = layouts.map((layoutFile) => readLayoutShape(layoutFile, layoutShapes));
+		const selection = selectPageLayout(layouts.map((layout, index) => ({
+			layout,
+			renders: shapes[index].renders
+		})));
+		if (selection.type === "rejected") throw new NestedLayoutsNotSupportedError(relativeToApp(pageFile), selection.layouts.map(relativeToApp));
+		const middlewareLayouts = layouts.filter((_, index) => shapes[index].hasMiddleware);
+		const layoutPrefix = layouts.reduce((composed, layoutFile) => composeRoutePath(composed, readDeclarations(layoutFile, declarations).prefix ?? "/"), "/");
+		pages.push({
+			routeName: route.name ?? deriveFallbackRouteName({
+				routePath: route.path,
+				sourceFile: relativeToApp(pageFile)
+			}),
+			routePath: composeRoutePath(layoutPrefix, route.path),
+			pageFile,
+			webRoot,
+			layouts,
+			middlewareLayouts,
+			...hasAppFile ? { appFile } : {}
+		});
+	}
+	pages.sort(comparePages);
+	assertUniqueRouteNames(pages, appRoot);
+	return pages;
+}
+
+//#endregion
+export { DuplicatePageRouteNameError, discoverPages, discoverWebRoots, isFile, layoutChainFor, toPosix, walkFiles };
+//# sourceMappingURL=discover-pages.mjs.map

package/esm/build/discover-pages.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover-pages.mjs","names":[],"sources":["../../../../../../../web/src/build/discover-pages.ts"],"sourcesContent":["/**\n * Static discovery of the application's page graph — the ONE scan every\n * provider shares.\n *\n * This module has a single responsibility: look at the filesystem and produce\n * the recipe. It writes nothing, knows nothing about the generated barrel, and\n * imports neither Vite nor a single application module. Everything that turns\n * the recipe into an artefact (the production barrel, the dev plugin, the\n * generated client entry) lives with that artefact and consumes\n * {@link discoverPages}.\n *\n * The reason it is one module rather than one function per consumer: two\n * scanners that agree today drift tomorrow, and a page that exists for the\n * server but not the client is the silent failure that costs a day to find.\n * Sharing the scan makes that disagreement impossible by construction instead\n * of catchable by test.\n *\n * \"Static\" means WITHOUT RUNNING THE APPLICATION — this module globs\n * `*.page.tsx`, `layout.tsx` and `root.tsx`, and reads each page's declared\n * `route` and each layout's declared `prefix` by PARSING the source\n * ({@link readRouteExports}). It still imports no application module.\n *\n * The route a page is served under is the one the page DECLARES, not the one\n * its directory suggests, so that is the route discovery reports. The\n * composition — EVERY layout `prefix` on the page's path, outermost first, plus\n * the page's own `route` path — and the fallback used when a route omits its\n * name are mirrored from the server's installer (`installPageRoutes`),\n * deliberately and in one direction: build and boot agree because one of them\n * copies the other, not because two conventions were written to match.\n *\n * Discovery also CLASSIFIES each layout — does its module have a default\n * export, does it export `middleware` — because the layout policy\n * ({@link \"../routing/layout-policy.ts\"}) owns the rule but may not touch a\n * filesystem to learn the facts the rule needs. That classification is another\n * parse, never an import: a layout is read exactly the way a page's `route` is.\n */\nimport fs from \"node:fs\";\nimport path from \"node:path\";\nimport { parse } from \"@babel/parser\";\nimport { composeRoutePath } from \"../routing/compose-route-path\";\nimport { NestedLayoutsNotSupportedError, selectPageLayout } from \"../routing/layout-policy\";\nimport { deriveFallbackRouteName } from \"../routing/route-identity\";\nimport type { RouteExportsReadResult } from \"./read-route-exports\";\nimport { NonLiteralRouteExportError, readRouteExports } from \"./read-route-exports\";\n\nexport type DiscoverPagesOptions = {\n  /** Absolute path to the application root (where `package.json` lives). */\n  appRoot: string;\n  /** Source directory name under `appRoot`; defaults to `\"src\"`. */\n  srcDir?: string;\n};\n\nexport type DiscoveredPage = {\n  /**\n   * The page's route name: the `name` its `route` export declares, or the\n   * server's own fallback derivation — `<module>.<declared path with dots>` for\n   * a page in a module's web tree, the dotted path alone for one in the global\n   * tree, and `index` when neither has anything to say.\n   *\n   * Unique across the whole graph — {@link discoverPages} refuses to return a\n   * result where it is not.\n   */\n  routeName: string;\n  /**\n   * The page's EFFECTIVE route path: the declared `prefix` of EVERY layout on\n   * its path — outermost first, wherever in the ancestry each lives — composed\n   * in order with the page's own declared `route` path, which is the path the\n   * server registers it under. A layout that declares no `prefix` contributes\n   * nothing. Always `/`-prefixed.\n   *\n   * Every layout, not just the rendering one: a `prefix`-only layout is a real\n   * segment of the URL its subtree lives under, and skipping it would serve the\n   * subtree from a path nobody wrote down.\n   */\n  routePath: string;\n  /** Absolute path to the `*.page.tsx` file. */\n  pageFile: string;\n  /** The web root this page was found under — the root its layout chain climbs to. */\n  webRoot: string;\n  /** Absolute paths of every `layout.tsx` from the web root down to the page's own directory, OUTERMOST FIRST. */\n  layouts: string[];\n  /**\n   * The page's middleware chain: the subset of {@link layouts} whose modules\n   * export `middleware`, OUTERMOST FIRST — the order they must run in.\n   *\n   * Source files rather than the middleware values themselves, because\n   * discovery never runs application code: this says WHICH layouts contribute a\n   * guard, and the consumer that already loads those modules reads the values\n   * off them.\n   *\n   * Empty when no layout on the path declares middleware, which is the common\n   * case; a page with no layouts always has an empty chain.\n   */\n  middlewareLayouts: string[];\n  /** Absolute path to the global `root.tsx` every page renders inside, when it exists. */\n  appFile?: string;\n};\n\n/** Raised when two pages claim one route name. */\nexport class DuplicatePageRouteNameError extends Error {\n  public constructor(\n    public readonly routeName: string,\n    public readonly firstFile: string,\n    public readonly secondFile: string,\n  ) {\n    super(\n      `Two pages resolve to the same route name \"${routeName}\": \"${firstFile}\" and ` +\n        `\"${secondFile}\". A route name identifies exactly one page, so the second ` +\n        \"page would be unreachable. To fix: rename one of the files, or move it so \" +\n        \"its directory gives it a different route name.\",\n    );\n    this.name = \"DuplicatePageRouteNameError\";\n  }\n}\n\nexport function toPosix(value: string): string {\n  return value.replace(/\\\\/g, \"/\");\n}\n\nfunction isDirectory(candidate: string): boolean {\n  try {\n    return fs.statSync(candidate).isDirectory();\n  } catch {\n    return false;\n  }\n}\n\nexport function isFile(candidate: string): boolean {\n  try {\n    return fs.statSync(candidate).isFile();\n  } catch {\n    return false;\n  }\n}\n\n/**\n * The two page roots: the global `src/web/**` tree and each\n * module's `src/app/<module>/web/**` tree. Both are optional; a project with\n * neither has zero pages, which is a legal empty state.\n */\nexport function discoverWebRoots(srcRoot: string): string[] {\n  const roots: string[] = [];\n  const globalRoot = path.join(srcRoot, \"web\");\n\n  if (isDirectory(globalRoot)) {\n    roots.push(globalRoot);\n  }\n\n  const appDir = path.join(srcRoot, \"app\");\n\n  if (isDirectory(appDir)) {\n    for (const entry of fs.readdirSync(appDir, { withFileTypes: true }).sort(byName)) {\n      if (!entry.isDirectory()) continue;\n\n      const moduleWebRoot = path.join(appDir, entry.name, \"web\");\n\n      if (isDirectory(moduleWebRoot)) {\n        roots.push(moduleWebRoot);\n      }\n    }\n  }\n\n  return roots;\n}\n\nfunction byName(left: { name: string }, right: { name: string }): number {\n  return left.name < right.name ? -1 : left.name > right.name ? 1 : 0;\n}\n\nexport type DiscoveredPageFile = {\n  /** Absolute path to the `*.page.tsx` file. */\n  pageFile: string;\n  /** The web root ({@link discoverWebRoots}) this page was found under. */\n  webRoot: string;\n};\n\n/**\n * The subject list: every `*.page.tsx` under BOTH web roots, one call for the\n * whole graph.\n *\n * Unlike {@link discoverPages}, this reads no `route` or `prefix` export and\n * throws on nothing — it answers only \"which page files exist\", so a provider\n * that still resolves a page's route by its own means (dev's\n * `ssrLoadModule`-driven installer, chiefly) can share the walk without\n * inheriting the static-parsing refusals that answering \"what route is this\"\n * requires.\n */\nexport function discoverPageFiles(srcRoot: string): DiscoveredPageFile[] {\n  const found: DiscoveredPageFile[] = [];\n\n  for (const webRoot of discoverWebRoots(srcRoot)) {\n    for (const pageFile of walkFiles(webRoot, (fileName) => fileName.endsWith(\".page.tsx\"))) {\n      found.push({ pageFile, webRoot });\n    }\n  }\n\n  return found;\n}\n\n/** Every file under `dir` (recursive) whose name matches `predicate`. */\nexport function walkFiles(dir: string, predicate: (fileName: string) => boolean): string[] {\n  const found: string[] = [];\n\n  for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort(byName)) {\n    const full = path.join(dir, entry.name);\n\n    if (entry.isDirectory()) {\n      found.push(...walkFiles(full, predicate));\n    } else if (entry.isFile() && predicate(entry.name)) {\n      found.push(full);\n    }\n  }\n\n  return found;\n}\n\n/**\n * A page's layout chain: every `layout.tsx` in the directories from its web\n * root down to its own directory, OUTERMOST FIRST.\n *\n * Dev's installer reads only the nearest layout today, because its page module\n * triple holds a single layout; the recipe carries the whole chain so the\n * runtime side can compose\n * nested layouts without a second discovery pass. The nearest layout is always\n * the LAST element, so a consumer that still wants dev's one-layout behaviour\n * reads `layouts.at(-1)`.\n */\nexport function layoutChainFor(pageFile: string, webRoot: string): string[] {\n  const chain: string[] = [];\n  const relativeDir = path.relative(webRoot, path.dirname(pageFile));\n  const segments = relativeDir === \"\" ? [] : relativeDir.split(path.sep);\n\n  let current = webRoot;\n\n  for (let index = 0; index <= segments.length; index++) {\n    if (index > 0) {\n      current = path.join(current, segments[index - 1]);\n    }\n\n    const candidate = path.join(current, \"layout.tsx\");\n\n    if (isFile(candidate)) {\n      chain.push(candidate);\n    }\n  }\n\n  return chain;\n}\n\nfunction compareStrings(left: string, right: string): number {\n  return left < right ? -1 : left > right ? 1 : 0;\n}\n\n/**\n * The total order every consumer sees, and the reason discovery returns an\n * array rather than a set: the page's SOURCE FILE PATH, lexicographic, POSIX.\n *\n * Serialization order only; matching precedence is a property of the route\n * grammar, not of this array.\n *\n * The file path rather than the route path, now that the route is the declared\n * one: a page's route can be rewritten by editing one line, which would reorder\n * an artefact that has not otherwise changed, while the file it lives in is the\n * stable identity the artefact is built from. It also carries no suggestion of\n * precedence — nobody reads \"sorted by file name\" as \"most specific first\",\n * which is the misreading a route-path order invites.\n *\n * Lexicographic because it is byte-comparable output across every provider,\n * which keeps diffs stable and keeps filesystem enumeration order out of the\n * artefact: two machines that list a directory differently must still produce\n * byte-identical output, or a build is only reproducible by luck.\n */\nfunction comparePages(left: DiscoveredPage, right: DiscoveredPage): number {\n  return compareStrings(toPosix(left.pageFile), toPosix(right.pageFile));\n}\n\nfunction assertUniqueRouteNames(pages: readonly DiscoveredPage[], appRoot: string): void {\n  const fileByRouteName = new Map<string, string>();\n\n  for (const page of pages) {\n    const existing = fileByRouteName.get(page.routeName);\n    const relative = toPosix(path.relative(appRoot, page.pageFile));\n\n    if (existing !== undefined) {\n      throw new DuplicatePageRouteNameError(page.routeName, existing, relative);\n    }\n\n    fileByRouteName.set(page.routeName, relative);\n  }\n}\n\n/** Raised when a `*.page.tsx` declares no `route` export. */\nexport class MissingRouteExportError extends Error {\n  public constructor(public readonly pageFile: string) {\n    super(\n      `\"${pageFile}\" is a page file but declares no \\`route\\` export. A page with no route is a ` +\n        \"page the dev server would still serve and production would 404 on, so the build refuses \" +\n        `it instead. For example: export const route = \"/list\";`,\n    );\n    this.name = \"MissingRouteExportError\";\n  }\n}\n\n/**\n * The declared exports of one file, or a thrown\n * {@link NonLiteralRouteExportError} when they cannot be read without running\n * the application. Layouts are read once per run and remembered: a layout is\n * the nearest one for every page beside it, and parsing it once per page would\n * be the same answer bought repeatedly.\n */\nfunction readDeclarations(sourceFile: string, cache: Map<string, RouteExportsReadResult>) {\n  let result = cache.get(sourceFile);\n\n  if (result === undefined) {\n    result = readRouteExports(sourceFile);\n    cache.set(sourceFile, result);\n  }\n\n  if (!result.ok) {\n    throw new NonLiteralRouteExportError(result.rejection);\n  }\n\n  return result;\n}\n\n/**\n * What a layout DOES, read by parsing it — the facts the layout policy's rule\n * needs and, being a pure module, cannot go and find for itself.\n */\ntype LayoutShape = {\n  /**\n   * Whether the module has a default export — the export that puts an element\n   * in the document, and therefore the one thing that makes a layout count\n   * against the single-rendering-layout rule.\n   */\n  renders: boolean;\n  /** Whether the module exports `middleware`, or might via a re-export this cannot see through. */\n  hasMiddleware: boolean;\n};\n\n/**\n * Parses one layout and reports its shape. Remembered per run for the same\n * reason declarations are: a layout is on the path of every page beneath it.\n */\nfunction readLayoutShape(layoutFile: string, cache: Map<string, LayoutShape>): LayoutShape {\n  const cached = cache.get(layoutFile);\n\n  if (cached !== undefined) return cached;\n\n  const source = fs.readFileSync(layoutFile, \"utf-8\");\n  let program: ReturnType<typeof parse>[\"program\"];\n\n  try {\n    program = parse(source, {\n      sourceType: \"module\",\n      // Every file this reads is a layout, i.e. `.tsx`.\n      plugins: [\"typescript\", \"jsx\"],\n      errorRecovery: false,\n    }).program;\n  } catch (error) {\n    throw new Error(\n      `Cannot read the exports of \"${layoutFile}\": the file could not be parsed ` +\n        `(${(error as Error).message}). Fix the syntax error and the build will continue.`,\n    );\n  }\n\n  const shape: LayoutShape = { renders: false, hasMiddleware: false };\n\n  for (const statement of program.body) {\n    if (statement.type === \"ExportDefaultDeclaration\") {\n      shape.renders = true;\n      continue;\n    }\n\n    // `export * from \"./guard\"` cannot re-export a default — the language\n    // excludes it — but it CAN contribute `middleware`, and no parse can see\n    // through it without resolving and reading another module. Reading it as\n    // \"no middleware here\" is exactly the silent unguarding this slice exists\n    // to prevent, so it is read as \"possibly\" and fails loudly downstream.\n    if (statement.type === \"ExportAllDeclaration\") {\n      shape.hasMiddleware = true;\n      continue;\n    }\n\n    if (statement.type !== \"ExportNamedDeclaration\" || statement.exportKind === \"type\") continue;\n\n    for (const specifier of statement.specifiers) {\n      if (specifier.type !== \"ExportSpecifier\" || specifier.exportKind === \"type\") continue;\n\n      const exported =\n        specifier.exported.type === \"Identifier\"\n          ? specifier.exported.name\n          : specifier.exported.value;\n\n      if (exported === \"default\") shape.renders = true;\n      if (exported === \"middleware\") shape.hasMiddleware = true;\n    }\n\n    const { declaration } = statement;\n\n    if (declaration === null || declaration === undefined) continue;\n\n    if (declaration.type === \"VariableDeclaration\") {\n      for (const declarator of declaration.declarations) {\n        if (declarator.id.type === \"Identifier\" && declarator.id.name === \"middleware\") {\n          shape.hasMiddleware = true;\n        }\n      }\n\n      continue;\n    }\n\n    if (\n      (declaration.type === \"FunctionDeclaration\" || declaration.type === \"ClassDeclaration\") &&\n      declaration.id?.name === \"middleware\"\n    ) {\n      shape.hasMiddleware = true;\n    }\n  }\n\n  cache.set(layoutFile, shape);\n\n  return shape;\n}\n\n/**\n * Scans both web roots and returns the pages in a defined total order.\n *\n * Zero pages is a legal result, not an error: a project may be configured\n * with web and have nothing to serve yet. What is an error is a `*.page.tsx`\n * with no `route` export, which is refused rather than silently omitted — an\n * artefact that leaves a page out is a page the dev server still serves and\n * production 404s on; two pages claiming one route name, which this refuses\n * to return at all — the alternative is an artefact in which one of them is\n * silently unreachable; a `route` or `prefix` that cannot be read without\n * running the application, which is refused before any page is reported at\n * all; and a page whose layout chain holds more than one RENDERING layout, which\n * the production installer would refuse anyway — discovery refuses it first so\n * that artefact is never produced.\n */\nexport function discoverPages(options: DiscoverPagesOptions): DiscoveredPage[] {\n  const { appRoot } = options;\n  const srcRoot = path.join(appRoot, options.srcDir ?? \"src\");\n  const webRoots = discoverWebRoots(srcRoot);\n  const appFile = path.join(srcRoot, \"web\", \"root.tsx\");\n  const hasAppFile = isFile(appFile);\n  const declarations = new Map<string, RouteExportsReadResult>();\n  const layoutShapes = new Map<string, LayoutShape>();\n  const relativeToApp = (file: string) => toPosix(path.relative(appRoot, file));\n\n  const pages: DiscoveredPage[] = [];\n\n  for (const webRoot of webRoots) {\n    for (const pageFile of walkFiles(webRoot, (fileName) => fileName.endsWith(\".page.tsx\"))) {\n      const { route } = readDeclarations(pageFile, declarations);\n\n      if (route === undefined) {\n        throw new MissingRouteExportError(relativeToApp(pageFile));\n      }\n\n      // The policy decides which layout the page RENDERS INSIDE, from the FULL\n      // enumerated chain: a layout anywhere on the ancestry path counts, not\n      // just one in the page's own directory. Discovery supplies the one fact\n      // the rule needs and the pure policy cannot learn — whether each layout\n      // renders anything at all.\n      const layouts = layoutChainFor(pageFile, webRoot);\n      const shapes = layouts.map((layoutFile) => readLayoutShape(layoutFile, layoutShapes));\n      const selection = selectPageLayout(\n        layouts.map((layout, index) => ({ layout, renders: shapes[index].renders })),\n      );\n\n      if (selection.type === \"rejected\") {\n        throw new NestedLayoutsNotSupportedError(\n          relativeToApp(pageFile),\n          selection.layouts.map(relativeToApp),\n        );\n      }\n\n      // Every layout that declares a guard, outermost first. Both installers\n      // now CONCATENATE the whole chain into the pipeline's single layout slot\n      // (`../server/install-page-routes.ts`, `../server/install-page-routes-from-manifest.ts`),\n      // so a guard anywhere on the path runs, in this order — which is why the\n      // temporary refusal that used to stand here is gone rather than relaxed.\n      const middlewareLayouts = layouts.filter((_, index) => shapes[index].hasMiddleware);\n\n      // EVERY prefix on the path, outermost first: a `prefix`-only layout is\n      // still a segment of the URL, and composing only the rendering layout's\n      // would serve the subtree from a path nobody declared.\n      const layoutPrefix = layouts.reduce(\n        (composed, layoutFile) =>\n          composeRoutePath(composed, readDeclarations(layoutFile, declarations).prefix ?? \"/\"),\n        \"/\",\n      );\n\n      pages.push({\n        routeName:\n          route.name ??\n          deriveFallbackRouteName({\n            routePath: route.path,\n            sourceFile: relativeToApp(pageFile),\n          }),\n        routePath: composeRoutePath(layoutPrefix, route.path),\n        pageFile,\n        webRoot,\n        layouts,\n        middlewareLayouts,\n        ...(hasAppFile ? { appFile } : {}),\n      });\n    }\n  }\n\n  pages.sort(comparePages);\n\n  assertUniqueRouteNames(pages, appRoot);\n\n  return pages;\n}\n"],"mappings":"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"}

package/esm/build/generate-client-registry.mjs

@@ -0,0 +1,123 @@
+//#region ../web/src/build/generate-client-registry.ts
+/** The name of the array the generated module exports. */
+const CLIENT_REGISTRY_EXPORT_NAME = "pages";
+/** The specifier the generated module imports its entry type from. */
+const CLIENT_RUNTIME_SPECIFIER = "@warlock.js/web/client/runtime";
+/**
+* Raised when two pages claim one route name.
+*
+* `discoverPages` promises uniqueness already (`discover-pages.ts:370`). This
+* asserts it anyway: the alternative is trusting an upstream promise and
+* emitting a registry in which one page is silently unreachable, which costs
+* far more to diagnose than the check costs to run.
+*/
+var DuplicateClientPageNameError = class extends Error {
+	routeName;
+	firstPageFile;
+	secondPageFile;
+	constructor(routeName, firstPageFile, secondPageFile) {
+		super(`Two pages claim the client route name "${routeName}": "${firstPageFile}" and "${secondPageFile}". A route name identifies exactly one page, so the second page would be unreachable in the browser. To fix: rename one page's \`route\` export, or move the file so its directory gives it a different route name.`);
+		this.routeName = routeName;
+		this.firstPageFile = firstPageFile;
+		this.secondPageFile = secondPageFile;
+		this.name = "DuplicateClientPageNameError";
+	}
+};
+/**
+* Every literal the generator emits goes through here, without exception.
+* Windows separators, quotes and backslashes are all in scope, and a
+* hand-quoted literal that gets one of them wrong fails at bundle time with a
+* parse error no user can act on.
+*/
+function quote(value) {
+	return JSON.stringify(value);
+}
+const HEADER = [
+	"// AUTO-GENERATED by @warlock.js/web — do not edit.",
+	"// The page graph, compiled into the CLIENT bundle.",
+	"//",
+	"// `name` and `path` are baked in as data so the client runtime can match a",
+	"// route before loading anything; every module reference is a dynamic",
+	"// `import()` so a page's code is downloaded only when that page is rendered.",
+	`import type { ClientPageEntry } from ${quote(CLIENT_RUNTIME_SPECIFIER)};`
+];
+function assertUniqueNames(pages) {
+	const pageFileByName = /* @__PURE__ */ new Map();
+	for (const page of pages) {
+		const existing = pageFileByName.get(page.routeName);
+		if (existing !== void 0) throw new DuplicateClientPageNameError(page.routeName, existing, page.pageFile);
+		pageFileByName.set(page.routeName, page.pageFile);
+	}
+}
+/**
+* One entry's `load`.
+*
+* It memoises NOTHING and holds no one-shot state: the runtime calls it again
+* on re-navigation to the same route, and a loader that works once and returns
+* undefined the second time is a silent blank page. Dynamic `import()` is
+* already module-cached by the bundler, so the correct implementation is to
+* let the cache do the caching.
+*/
+function loadSource(page, toImportSpecifier) {
+	const bindings = ["Page"];
+	const specifiers = [toImportSpecifier(page.pageFile)];
+	const layoutBindings = page.layouts.map((layoutFile, index) => {
+		bindings.push(`layout${index}`);
+		specifiers.push(toImportSpecifier(layoutFile));
+		return `layout${index}`;
+	});
+	if (page.appFile !== void 0) {
+		bindings.push("App");
+		specifiers.push(toImportSpecifier(page.appFile));
+	}
+	const app = page.appFile === void 0 ? "" : ", App";
+	return [
+		"    load: async () => {",
+		`      const [${bindings.join(", ")}] = await Promise.all([`,
+		...specifiers.map((specifier) => `        import(${quote(specifier)}),`),
+		"      ]);",
+		"",
+		`      return { Page, layouts: [${layoutBindings.join(", ")}]${app} };`,
+		"    },"
+	];
+}
+function entrySource(page, toImportSpecifier) {
+	return [
+		"  {",
+		"    type: \"page\",",
+		`    name: ${quote(page.routeName)},`,
+		`    path: ${quote(page.routePath)},`,
+		...loadSource(page, toImportSpecifier),
+		"  },"
+	];
+}
+/**
+* Returns the SOURCE of the client page registry module. Writes nothing.
+*
+* Zero pages is a legal result, not an error, and it is emitted as an explicit
+* empty registry: "built with web, no pages" must reach the runtime as a fact
+* rather than as a missing module.
+*/
+function generateClientRegistry(options) {
+	const { pages, toImportSpecifier } = options;
+	assertUniqueNames(pages);
+	const declaration = `export const ${CLIENT_REGISTRY_EXPORT_NAME}: readonly ClientPageEntry[] =`;
+	if (pages.length === 0) return [
+		...HEADER,
+		"",
+		`${declaration} [];`,
+		""
+	].join("\n");
+	return [
+		...HEADER,
+		"",
+		`${declaration} [`,
+		...pages.flatMap((page) => entrySource(page, toImportSpecifier)),
+		"];",
+		""
+	].join("\n");
+}
+
+//#endregion
+export { generateClientRegistry };
+//# sourceMappingURL=generate-client-registry.mjs.map

package/esm/build/generate-client-registry.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-client-registry.mjs","names":[],"sources":["../../../../../../../web/src/build/generate-client-registry.ts"],"sourcesContent":["/**\n * The CLIENT half of the build→runtime handoff: the source of a generated\n * module that carries the page graph into the BROWSER.\n *\n * `generate-pages-barrel.ts` is the server half. The two are deliberately not\n * one function, because they want opposite things from the same recipe: the\n * server barrel emits STATIC `import * as` so every page lands in the one\n * server bundle and its route can be read off the module at boot, while the\n * browser must never download page B to render page A — so every module\n * reference here is a dynamic `import()`, and `name`/`path` are baked in as\n * DATA so the client runtime can match a route before loading anything.\n *\n * This function is PURE. It reads no filesystem, writes no file, and does not\n * call {@link discoverPages} — the caller passes the already-discovered graph\n * in. That is what keeps the \"one discovery run, one graph\" invariant: names\n * and paths agree with the server's because there is only ever one scan, not\n * because two scanners were written to match.\n *\n * Module RESOLUTION is the one thing that legitimately differs between the dev\n * provider and the production provider, so it is injected as\n * {@link GenerateClientRegistryOptions.toImportSpecifier} rather than computed\n * here. No provider-specific data — no Vite ids, no `/@fs/` prefixes, no\n * hashed chunk urls, no HMR metadata — reaches the emitted entry, and every\n * other property stays testable with a trivial mapper.\n */\nimport type { DiscoveredPage } from \"./discover-pages\";\n\nexport type GenerateClientRegistryOptions = {\n  /**\n   * The discovered page graph, IN THE ORDER DISCOVERY GAVE IT.\n   *\n   * `discoverPages` already sorts by POSIX source-file path\n   * (`discover-pages.ts:368`, comparator at `discover-pages.ts:248-250`), so\n   * this emitter preserves that order rather than imposing a second one: two\n   * orderings of one graph is exactly the drift the shared scan exists to\n   * prevent. Serialization stability only — nothing emitted here implies\n   * matching precedence, which is a property of the route grammar.\n   */\n  pages: readonly DiscoveredPage[];\n  /** Maps an absolute source file path to the specifier the emitted module will import. */\n  toImportSpecifier: (absoluteFilePath: string) => string;\n};\n\n/** The name of the array the generated module exports. */\nexport const CLIENT_REGISTRY_EXPORT_NAME = \"pages\";\n\n/** The specifier the generated module imports its entry type from. */\nconst CLIENT_RUNTIME_SPECIFIER = \"@warlock.js/web/client/runtime\";\n\n/**\n * Raised when two pages claim one route name.\n *\n * `discoverPages` promises uniqueness already (`discover-pages.ts:370`). This\n * asserts it anyway: the alternative is trusting an upstream promise and\n * emitting a registry in which one page is silently unreachable, which costs\n * far more to diagnose than the check costs to run.\n */\nexport class DuplicateClientPageNameError extends Error {\n  public constructor(\n    public readonly routeName: string,\n    public readonly firstPageFile: string,\n    public readonly secondPageFile: string,\n  ) {\n    super(\n      `Two pages claim the client route name \"${routeName}\": \"${firstPageFile}\" and ` +\n        `\"${secondPageFile}\". A route name identifies exactly one page, so the second ` +\n        \"page would be unreachable in the browser. To fix: rename one page's `route` \" +\n        \"export, or move the file so its directory gives it a different route name.\",\n    );\n    this.name = \"DuplicateClientPageNameError\";\n  }\n}\n\n/**\n * Every literal the generator emits goes through here, without exception.\n * Windows separators, quotes and backslashes are all in scope, and a\n * hand-quoted literal that gets one of them wrong fails at bundle time with a\n * parse error no user can act on.\n */\nfunction quote(value: string): string {\n  return JSON.stringify(value);\n}\n\nconst HEADER = [\n  \"// AUTO-GENERATED by @warlock.js/web — do not edit.\",\n  \"// The page graph, compiled into the CLIENT bundle.\",\n  \"//\",\n  \"// `name` and `path` are baked in as data so the client runtime can match a\",\n  \"// route before loading anything; every module reference is a dynamic\",\n  \"// `import()` so a page's code is downloaded only when that page is rendered.\",\n  `import type { ClientPageEntry } from ${quote(CLIENT_RUNTIME_SPECIFIER)};`,\n];\n\nfunction assertUniqueNames(pages: readonly DiscoveredPage[]): void {\n  const pageFileByName = new Map<string, string>();\n\n  for (const page of pages) {\n    const existing = pageFileByName.get(page.routeName);\n\n    if (existing !== undefined) {\n      throw new DuplicateClientPageNameError(page.routeName, existing, page.pageFile);\n    }\n\n    pageFileByName.set(page.routeName, page.pageFile);\n  }\n}\n\n/**\n * One entry's `load`.\n *\n * It memoises NOTHING and holds no one-shot state: the runtime calls it again\n * on re-navigation to the same route, and a loader that works once and returns\n * undefined the second time is a silent blank page. Dynamic `import()` is\n * already module-cached by the bundler, so the correct implementation is to\n * let the cache do the caching.\n */\nfunction loadSource(page: DiscoveredPage, toImportSpecifier: (file: string) => string): string[] {\n  const bindings = [\"Page\"];\n  const specifiers = [toImportSpecifier(page.pageFile)];\n\n  // Outermost first, exactly as discovery enumerated the chain — the order IS\n  // the nesting, so reordering it would silently reparent the page.\n  const layoutBindings = page.layouts.map((layoutFile, index) => {\n    bindings.push(`layout${index}`);\n    specifiers.push(toImportSpecifier(layoutFile));\n\n    return `layout${index}`;\n  });\n\n  if (page.appFile !== undefined) {\n    bindings.push(\"App\");\n    specifiers.push(toImportSpecifier(page.appFile));\n  }\n\n  // `App` is OMITTED, never emitted as `App: undefined`: the runtime validator\n  // reads an own `App` key as a promise that a module namespace is behind it.\n  const app = page.appFile === undefined ? \"\" : \", App\";\n\n  return [\n    \"    load: async () => {\",\n    `      const [${bindings.join(\", \")}] = await Promise.all([`,\n    ...specifiers.map((specifier) => `        import(${quote(specifier)}),`),\n    \"      ]);\",\n    \"\",\n    `      return { Page, layouts: [${layoutBindings.join(\", \")}]${app} };`,\n    \"    },\",\n  ];\n}\n\nfunction entrySource(\n  page: DiscoveredPage,\n  toImportSpecifier: (file: string) => string,\n): string[] {\n  return [\n    \"  {\",\n    '    type: \"page\",',\n    // Verbatim from discovery, both of them. `routePath` in particular is NOT\n    // re-derived or re-normalised here: discovery already composed the layout\n    // prefix with the declared route, and a second composition is a second\n    // convention waiting to disagree with the server's.\n    `    name: ${quote(page.routeName)},`,\n    `    path: ${quote(page.routePath)},`,\n    ...loadSource(page, toImportSpecifier),\n    \"  },\",\n  ];\n}\n\n/**\n * Returns the SOURCE of the client page registry module. Writes nothing.\n *\n * Zero pages is a legal result, not an error, and it is emitted as an explicit\n * empty registry: \"built with web, no pages\" must reach the runtime as a fact\n * rather than as a missing module.\n */\nexport function generateClientRegistry(options: GenerateClientRegistryOptions): string {\n  const { pages, toImportSpecifier } = options;\n\n  assertUniqueNames(pages);\n\n  const declaration = `export const ${CLIENT_REGISTRY_EXPORT_NAME}: readonly ClientPageEntry[] =`;\n\n  if (pages.length === 0) {\n    return [...HEADER, \"\", `${declaration} [];`, \"\"].join(\"\\n\");\n  }\n\n  return [\n    ...HEADER,\n    \"\",\n    `${declaration} [`,\n    ...pages.flatMap((page) => entrySource(page, toImportSpecifier)),\n    \"];\",\n    \"\",\n  ].join(\"\\n\");\n}\n"],"mappings":";;AA4CA,MAAa,8BAA8B;;AAG3C,MAAM,2BAA2B;;;;;;;;;AAUjC,IAAa,+BAAb,cAAkD,MAAM;CAEpC;CACA;CACA;CAHlB,AAAO,YACL,AAAgB,WAChB,AAAgB,eAChB,AAAgB,gBAChB;EACA,MACE,0CAA0C,UAAU,MAAM,cAAc,SAClE,eAAe,oNAGvB;EATgB;EACA;EACA;EAQhB,KAAK,OAAO;CACd;AACF;;;;;;;AAQA,SAAS,MAAM,OAAuB;CACpC,OAAO,KAAK,UAAU,KAAK;AAC7B;AAEA,MAAM,SAAS;CACb;CACA;CACA;CACA;CACA;CACA;CACA,wCAAwC,MAAM,wBAAwB,EAAE;AAC1E;AAEA,SAAS,kBAAkB,OAAwC;CACjE,MAAM,iCAAiB,IAAI,IAAoB;CAE/C,KAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,WAAW,eAAe,IAAI,KAAK,SAAS;EAElD,IAAI,aAAa,QACf,MAAM,IAAI,6BAA6B,KAAK,WAAW,UAAU,KAAK,QAAQ;EAGhF,eAAe,IAAI,KAAK,WAAW,KAAK,QAAQ;CAClD;AACF;;;;;;;;;;AAWA,SAAS,WAAW,MAAsB,mBAAuD;CAC/F,MAAM,WAAW,CAAC,MAAM;CACxB,MAAM,aAAa,CAAC,kBAAkB,KAAK,QAAQ,CAAC;CAIpD,MAAM,iBAAiB,KAAK,QAAQ,KAAK,YAAY,UAAU;EAC7D,SAAS,KAAK,SAAS,OAAO;EAC9B,WAAW,KAAK,kBAAkB,UAAU,CAAC;EAE7C,OAAO,SAAS;CAClB,CAAC;CAED,IAAI,KAAK,YAAY,QAAW;EAC9B,SAAS,KAAK,KAAK;EACnB,WAAW,KAAK,kBAAkB,KAAK,OAAO,CAAC;CACjD;CAIA,MAAM,MAAM,KAAK,YAAY,SAAY,KAAK;CAE9C,OAAO;EACL;EACA,gBAAgB,SAAS,KAAK,IAAI,EAAE;EACpC,GAAG,WAAW,KAAK,cAAc,kBAAkB,MAAM,SAAS,EAAE,GAAG;EACvE;EACA;EACA,kCAAkC,eAAe,KAAK,IAAI,EAAE,GAAG,IAAI;EACnE;CACF;AACF;AAEA,SAAS,YACP,MACA,mBACU;CACV,OAAO;EACL;EACA;EAKA,aAAa,MAAM,KAAK,SAAS,EAAE;EACnC,aAAa,MAAM,KAAK,SAAS,EAAE;EACnC,GAAG,WAAW,MAAM,iBAAiB;EACrC;CACF;AACF;;;;;;;;AASA,SAAgB,uBAAuB,SAAgD;CACrF,MAAM,EAAE,OAAO,sBAAsB;CAErC,kBAAkB,KAAK;CAEvB,MAAM,cAAc,gBAAgB,4BAA4B;CAEhE,IAAI,MAAM,WAAW,GACnB,OAAO;EAAC,GAAG;EAAQ;EAAI,GAAG,YAAY;EAAO;CAAE,CAAC,CAAC,KAAK,IAAI;CAG5D,OAAO;EACL,GAAG;EACH;EACA,GAAG,YAAY;EACf,GAAG,MAAM,SAAS,SAAS,YAAY,MAAM,iBAAiB,CAAC;EAC/D;EACA;CACF,CAAC,CAAC,KAAK,IAAI;AACb"}