@akanjs/devkit 3.0.0-alpha.103 → 3.0.0-alpha.105

package/artifact/implicitRootLayout.test.ts

@@ -50,7 +50,9 @@ describe("resolveSsrPageEntries", () => {
     expect(groupedRoot?.seedAbsPaths).toContain(groupedLayoutPath);
 
     const generatedSource = await Bun.file(groupedRoot?.moduleAbsPath ?? "").text();
-    expect(generatedSource).toContain('import * as inheritedLayout from "../../../page/_layout.tsx";');
+    // Both user modules go through the route resolver, so a `rootLayout()` chain and the legacy exports read alike.
+    expect(generatedSource).toContain('import * as inheritedModule from "../../../page/_layout.tsx";');
+    expect(generatedSource).toContain("const inheritedLayout = resolveRouteModule(inheritedModule as never");
     expect(generatedSource).not.toContain("<System.Provider");
     expect(generatedSource).toContain("export async function generateMetadata(props: PageProps)");
     expect(generatedSource).toContain("if (userLayout.generateMetadata) return userLayout.generateMetadata(props);");

package/artifact/implicitRootLayout.ts

@@ -185,13 +185,17 @@ async function writeGeneratedRootLayoutFile(opts: {
   const clientImport = opts.includeStInit
     ? `import { st } from "@apps/${opts.appName}/client";\nvoid st;\n`
     : `import "@apps/${opts.appName}/client";\n`;
+  // Both user modules go through `resolveRouteModule`: a `rootLayout()` chain and the legacy named exports read
+  // the same afterwards, and this file never has to know which shape the app wrote.
+  const inheritedLabel = inheritedSourceAbsPath ? path.relative(opts.appCwdPath, inheritedSourceAbsPath) : "";
   const inheritedImport = inheritedSourceSpecifier
-    ? `import * as inheritedLayout from ${JSON.stringify(inheritedSourceSpecifier)};\n`
-    : "const inheritedLayout = {};\n";
+    ? `import * as inheritedModule from ${JSON.stringify(inheritedSourceSpecifier)};\nconst inheritedLayout = resolveRouteModule(inheritedModule as never, ${JSON.stringify(inheritedLabel)}).module as LayoutModule;\n`
+    : "const inheritedLayout: LayoutModule = {};\n";
   const prefix = routePrefixForSegments(opts.boundary.segments);
+  const userLabel = opts.boundary.sourceAbsPath ? path.relative(opts.appCwdPath, opts.boundary.sourceAbsPath) : "";
   const userImport = sourceSpecifier
-    ? `import UserLayout, * as userLayout from ${JSON.stringify(sourceSpecifier)};\n`
-    : "const UserLayout = ({ children }) => children;\nconst userLayout = {};\n";
+    ? `import * as userModule from ${JSON.stringify(sourceSpecifier)};\nconst userLayout = resolveRouteModule(userModule as never, ${JSON.stringify(userLabel)}).module as LayoutModule;\nconst UserLayout = userLayout.default as (props: LayoutProps) => ReactNode | Promise<ReactNode>;\n`
+    : "const UserLayout = ({ children }: LayoutProps) => children;\nconst userLayout: LayoutModule = {};\n";
   const isAsyncUserLayout = opts.boundary.sourceAbsPath
     ? await AsyncDefaultExportDetector.detect(opts.boundary.sourceAbsPath)
     : false;
@@ -212,8 +216,9 @@ async function writeGeneratedRootLayoutFile(opts: {
   const layoutChild = isAsyncUserLayout ? "{layout}" : userLayoutElement;
   const layoutReturn = isAsyncUserLayout ? "layout" : userLayoutElement;
   const source = opts.includeSystemProvider
-    ? `import type { LayoutProps, PageProps } from "akanjs/client";
-import { loadFonts } from "akanjs/client";
+    ? `import type { LayoutModule, LayoutProps, PageProps } from "akanjs/client";
+import { loadFonts, resolveRouteModule } from "akanjs/client";
+import type { ReactNode } from "react";
 import { System } from "akanjs/ui";
 import { env } from "@apps/${opts.appName}/env/env.client";
 import { allDictionary } from ${JSON.stringify(dictMacroSpecifier)};
@@ -264,7 +269,9 @@ ${layoutBinding}  return (
   );
 }
 `
-    : `import type { LayoutProps, PageProps } from "akanjs/client";
+    : `import type { LayoutModule, LayoutProps, PageProps } from "akanjs/client";
+import { resolveRouteModule } from "akanjs/client";
+import type { ReactNode } from "react";
 ${inheritedImport}${userImport}
 export async function generateHead(props: PageProps) {
   if (userLayout.generateHead) return userLayout.generateHead(props);

package/executors.test.ts

@@ -595,9 +595,7 @@ describe("Workspace and app executor environment contracts", () => {
         "_index.tsx": `export const pageConfig = { devOnly: process.env.NODE_ENV !== "production" };\n${PAGE_SOURCE}`,
       });
 
-      await expect(app.getPageKeys({ refresh: true })).rejects.toThrow(
-        "pageConfig.devOnly must be a literal true or false",
-      );
+      await expect(app.getPageKeys({ refresh: true })).rejects.toThrow("devOnly must be a literal true or false");
     });
 
     test("reads devOnly through a satisfies annotation", async () => {

package/executors.ts

@@ -1548,6 +1548,7 @@ export class AppExecutor extends SysExecutor {
         else {
           const info = validator.validateRouteSourceExports(routeSource, absPath, parsed.kind, {
             rootLayout: isRootLayout,
+            pattern: parsed.pattern,
           });
           if (info.devOnly) {
             devOnlyKeys.add(key);

package/integration/devStabilityHarness.ts

@@ -159,19 +159,20 @@ export const server = new AkanServer("${this.appName}", {
       this.writeFile(
         "page/_layout.tsx",
         `import "./styles.css";
-import type { LayoutProps } from "akanjs/client";
+import { layout } from "akanjs/client";
 
-export default function Layout({ children }: LayoutProps) {
+export default layout().render(({ children }) => {
   return <>{children}</>;
-}
+});
 `,
       ),
       this.writeFile(
         "page/_index.tsx",
-        `import { marker } from "../common/marker";
+        `import { page } from "akanjs/client";
+import { marker } from "../common/marker";
 import { ClientMarker } from "../ui/ClientMarker";
 
-export default function Page() {
+export default page().render(() => {
   return (
     <main>
       <h1>Dev stability fixture</h1>
@@ -179,7 +180,7 @@ export default function Page() {
       <ClientMarker />
     </main>
   );
-}
+});
 `,
       ),
       // A second route exists so a test can ask for a page the backend has *never* built, at a moment of
@@ -187,16 +188,17 @@ export default function Page() {
       // request of a test is the only one that reaches the builder at all.
       this.writeFile(
         "page/second/_index.tsx",
-        `import { ClientMarker } from "../../ui/ClientMarker";
+        `import { page } from "akanjs/client";
+import { ClientMarker } from "../../ui/ClientMarker";
 
-export default function Page() {
+export default page().render(() => {
   return (
     <main>
       <h1>Second route</h1>
       <ClientMarker />
     </main>
   );
-}
+});
 `,
       ),
       this.writeFile(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-alpha.103",
+  "version": "3.0.0-alpha.105",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -44,7 +44,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "3.0.0-alpha.103",
+    "akanjs": "3.0.0-alpha.105",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",

package/routeSourceValidator.test.ts

@@ -39,3 +39,66 @@ describe("RouteSourceValidator", () => {
     });
   });
 });
+
+describe("RouteSourceValidator route chains", () => {
+  const chain = (source: string, kind: "page" | "layout", pattern: string) =>
+    RouteSourceValidator.validateRouteSourceExports(source, `page/${kind}.tsx`, kind, { pattern });
+
+  test("reads params, prompt and devOnly off a page() chain without evaluating it", () => {
+    const source = [
+      'import { page } from "akanjs/client";',
+      "export default page()",
+      '  .param("projectId", ID, { desc: "The project." })',
+      '  .search("status", String)',
+      "  .config({ transition: 'stack', devOnly: true })",
+      '  .prompt("briefProject", "Brief one project.")',
+      "  .render(async ({ projectId }) => null);",
+    ].join("\n");
+    expect(chain(source, "page", "/:lang/project/:projectId")).toEqual({
+      devOnly: true,
+      chain: { kind: "page", params: ["projectId"], prompt: "briefProject" },
+    });
+  });
+
+  test("names a [segment] the page did not declare and a .param() the path lacks", () => {
+    expect(() => chain("export default page().render(() => null);", "page", "/:lang/org/:orgId")).toThrow(
+      'sits under [orgId] but declares no .param("orgId")',
+    );
+    expect(() => chain('export default page().param("orgId", ID).render(() => null);', "page", "/:lang/org")).toThrow(
+      'declares .param("orgId") but no [orgId] segment is in its path',
+    );
+    expect(() =>
+      chain('export default page().param("lang", String).render(() => null);', "page", "/:lang/org"),
+    ).toThrow('declares .param("lang"), which every route receives undeclared');
+    // A layout may leave a segment undeclared.
+    expect(() =>
+      chain("export default layout().render(({ children }) => children);", "layout", "/:lang/org/:orgId"),
+    ).not.toThrow();
+  });
+
+  test("refuses named exports beside a chain, a chain in the wrong file kind, and a computed name", () => {
+    expect(() =>
+      chain(["export default page().render(() => null);", "export const pageConfig = {};"].join("\n"), "page", "/"),
+    ).toThrow("exports pageConfig beside its page() chain");
+    expect(() => chain("export default layout().render(() => null);", "page", "/")).toThrow(
+      "is a page file but exports layout()",
+    );
+    expect(() => chain("export default page().render(() => null);", "layout", "/")).toThrow(
+      "is a layout file but exports page()",
+    );
+    expect(() => chain("export default page().param(name, ID).render(() => null);", "page", "/:lang/:x")).toThrow(
+      ".param() takes a string literal first",
+    );
+    expect(() => chain("export default page().config({ devOnly: flag }).render(() => null);", "page", "/")).toThrow(
+      "devOnly must be a literal true or false",
+    );
+  });
+
+  test("still reads the legacy shape as before", () => {
+    const source = [
+      "export default function Page() { return null; }",
+      "export const pageConfig = { devOnly: false };",
+    ].join("\n");
+    expect(chain(source, "page", "/")).toEqual({ devOnly: false });
+  });
+});

package/routeSourceValidator.ts

@@ -3,10 +3,27 @@ import ts from "typescript";
 
 /** What the build needs out of a route module without evaluating it. */
 export interface RouteSourceInfo {
-  /** `pageConfig.devOnly === true`, read straight off the AST. */
+  /** `pageConfig.devOnly === true`, or `.config({ devOnly: true })` on a chain, read straight off the AST. */
   devOnly: boolean;
+  /** Present when the default export is a `page()` / `layout()` / `rootLayout()` chain. */
+  chain?: RouteSourceChain;
 }
 
+export interface RouteSourceChain {
+  kind: "page" | "layout" | "rootLayout";
+  /** The `.param()` names, in chain order. */
+  params: string[];
+  /** The `.prompt()` name, when the page publishes itself as an MCP prompt. */
+  prompt?: string;
+}
+
+interface ChainStage {
+  name: string;
+  args: ts.NodeArray<ts.Expression>;
+}
+
+const chainRoots = new Set(["page", "layout", "rootLayout"]);
+
 /**
  * Static enforcement of the `page/` route conventions, split out of `executors.ts` so that importing
  * an executor does not pull `typescript` (+65MB resident) into the module graph. Both validators need
@@ -21,7 +38,7 @@ export class RouteSourceValidator {
     source: string,
     filePath: string,
     kind: "page" | "layout",
-    options: { rootLayout?: boolean } = {},
+    options: { rootLayout?: boolean; pattern?: string } = {},
   ): RouteSourceInfo {
     const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
     const allowed = getRouteExports(kind, { rootLayout: options.rootLayout });
@@ -81,7 +98,91 @@ export class RouteSourceValidator {
     if (exported.has("metadata") && exported.has("generateMetadata")) {
       throw new Error(`[route-convention] metadata and generateMetadata cannot both be exported in ${filePath}`);
     }
-    return { devOnly: RouteSourceValidator.#readDevOnly(sourceFile, filePath) };
+    const chain = RouteSourceValidator.#readChain(sourceFile, filePath);
+    if (!chain) return { devOnly: RouteSourceValidator.#readDevOnly(sourceFile, filePath) };
+    const named = [...exported].filter((name) => name !== "default");
+    if (named.length)
+      throw new Error(
+        `[route-convention] ${filePath} exports ${named.join(", ")} beside its ${chain.kind}() chain — every route setting is a stage of the chain`,
+      );
+    if (kind === "page" && chain.kind !== "page")
+      throw new Error(`[route-convention] ${filePath} is a page file but exports ${chain.kind}()`);
+    if (kind === "layout" && chain.kind === "page")
+      throw new Error(`[route-convention] ${filePath} is a layout file but exports page()`);
+    if (options.pattern) RouteSourceValidator.#assertChainParams(chain, options.pattern, filePath);
+    return {
+      devOnly: chain.devOnly,
+      chain: { kind: chain.kind, params: chain.params, ...(chain.prompt ? { prompt: chain.prompt } : {}) },
+    };
+  }
+
+  /**
+   * The default export as a `page()` / `layout()` / `rootLayout()` chain, or null when the module is the legacy
+   * shape. Read off the source for the same reason `devOnly` is: the build enumerates routes without importing
+   * them, and `akan sync` should name a `[projectId]` folder whose page declares no `.param("projectId")` before
+   * the first request does.
+   */
+  static #readChain(sourceFile: ts.SourceFile, filePath: string) {
+    for (const statement of sourceFile.statements) {
+      if (!ts.isExportAssignment(statement) || statement.isExportEquals) continue;
+      let node = RouteSourceValidator.#unwrapExpression(statement.expression);
+      const stages: ChainStage[] = [];
+      while (node && ts.isCallExpression(node)) {
+        const callee = node.expression;
+        if (ts.isPropertyAccessExpression(callee)) {
+          stages.unshift({ name: callee.name.text, args: node.arguments });
+          node = callee.expression;
+          continue;
+        }
+        if (ts.isIdentifier(callee) && chainRoots.has(callee.text))
+          return RouteSourceValidator.#chainOf(callee.text as RouteSourceChain["kind"], stages, filePath);
+        return null;
+      }
+      return null;
+    }
+    return null;
+  }
+
+  static #chainOf(kind: RouteSourceChain["kind"], stages: ChainStage[], filePath: string) {
+    const params: string[] = [];
+    let prompt: string | undefined;
+    let devOnly = false;
+    const literal = (stage: ChainStage) => {
+      const first = stage.args[0];
+      if (!first || !ts.isStringLiteralLike(first))
+        throw new Error(
+          `[route-convention] .${stage.name}() takes a string literal first in ${filePath} — the build reads it without evaluating the module`,
+        );
+      return first.text;
+    };
+    for (const stage of stages) {
+      if (stage.name === "param") params.push(literal(stage));
+      else if (stage.name === "prompt") prompt = literal(stage);
+      else if (stage.name === "config")
+        devOnly = RouteSourceValidator.#devOnlyOf(RouteSourceValidator.#unwrapExpression(stage.args[0]), filePath);
+    }
+    return { kind, params, prompt, devOnly };
+  }
+
+  /** The same rule the loader applies: a page names every `[x]` it sits under, a layout may name a subset. */
+  static #assertChainParams(chain: { kind: string; params: string[] }, pattern: string, filePath: string) {
+    const inPath = pattern
+      .split("/")
+      .filter((part) => part.startsWith(":"))
+      .map((part) => part.slice(1))
+      .filter((name) => name !== "lang");
+    if (chain.params.includes("lang"))
+      throw new Error(`[route-convention] ${filePath} declares .param("lang"), which every route receives undeclared`);
+    const unknown = chain.params.find((name) => !inPath.includes(name));
+    if (unknown)
+      throw new Error(
+        `[route-convention] ${filePath} declares .param("${unknown}") but no [${unknown}] segment is in its path`,
+      );
+    const undeclared = inPath.find((name) => !chain.params.includes(name));
+    if (chain.kind === "page" && undeclared)
+      throw new Error(
+        `[route-convention] ${filePath} sits under [${undeclared}] but declares no .param("${undeclared}") — a page reads only what it declares`,
+      );
   }
 
   /**
@@ -98,24 +199,30 @@ export class RouteSourceValidator {
       for (const declaration of statement.declarationList.declarations) {
         if (!ts.isIdentifier(declaration.name) || declaration.name.text !== "pageConfig") continue;
         const initializer = RouteSourceValidator.#unwrapExpression(declaration.initializer);
-        if (!initializer || !ts.isObjectLiteralExpression(initializer)) continue;
-        for (const property of initializer.properties) {
-          if (!ts.isPropertyAssignment(property)) continue;
-          const name = property.name;
-          const key = ts.isIdentifier(name) ? name.text : ts.isStringLiteral(name) ? name.text : null;
-          if (key !== "devOnly") continue;
-          const value = RouteSourceValidator.#unwrapExpression(property.initializer);
-          if (value?.kind === ts.SyntaxKind.TrueKeyword) return true;
-          if (value?.kind === ts.SyntaxKind.FalseKeyword) return false;
-          throw new Error(
-            `[route-convention] pageConfig.devOnly must be a literal true or false in ${filePath} — the build reads it without evaluating the module`,
-          );
-        }
+        if (initializer && ts.isObjectLiteralExpression(initializer))
+          return RouteSourceValidator.#devOnlyOf(initializer, filePath);
       }
     }
     return false;
   }
 
+  static #devOnlyOf(config: ts.Expression | undefined, filePath: string): boolean {
+    if (!config || !ts.isObjectLiteralExpression(config)) return false;
+    for (const property of config.properties) {
+      if (!ts.isPropertyAssignment(property)) continue;
+      const name = property.name;
+      const key = ts.isIdentifier(name) ? name.text : ts.isStringLiteral(name) ? name.text : null;
+      if (key !== "devOnly") continue;
+      const value = RouteSourceValidator.#unwrapExpression(property.initializer);
+      if (value?.kind === ts.SyntaxKind.TrueKeyword) return true;
+      if (value?.kind === ts.SyntaxKind.FalseKeyword) return false;
+      throw new Error(
+        `[route-convention] devOnly must be a literal true or false in ${filePath} — the build reads it without evaluating the module`,
+      );
+    }
+    return false;
+  }
+
   static #unwrapExpression(expression?: ts.Expression): ts.Expression | undefined {
     let current = expression;
     while (

package/transforms/asyncDefaultExportDetector.ts

@@ -65,6 +65,8 @@ export class AsyncDefaultExportDetector {
 
       if (ts.isExportAssignment(statement)) {
         if (this.#isAsyncFunctionExpression(statement.expression)) return true;
+        // `export default layout()….render(fn)`: the loader unfolds the chain into an async adapter whatever `fn` is.
+        if (ts.isCallExpression(statement.expression)) return true;
         if (ts.isIdentifier(statement.expression)) defaultIdentifier = statement.expression.text;
         continue;
       }