proteum 2.1.9-8 → 2.2.0

package/README.md

@@ -26,7 +26,7 @@ Proteum combines:
 
 ## Core Principles
 
-- **Server-first by default.** Put data loading in the page setup function and keep client code focused on UI.
+- **Server-first by default.** Put data loading in the page data function and keep client code focused on UI.
 - **Explicit request entrypoints.** Controllers are classes. Request access is explicit through `this.request`.
 - **Local validation.** Validate handler input inside the handler with `this.input(schema)`.
 - **Deterministic generation.** Proteum owns `.proteum/` and regenerates it from source.
@@ -71,7 +71,7 @@ Important files:
 - `process.env` / optional `.env`: `PORT`, `ENV_*`, `URL`, `URL_INTERNAL`, any app-chosen variables referenced by `proteum.config.ts`, and `TRACE_*` environment variables loaded by the app
 - `server/config/*.ts`: plain typed config exports consumed by the explicit app bootstrap
 - `server/index.ts`: default-exported `Application` subclass that instantiates root services and router plugins
-- `client/pages/**`: SSR page entrypoints registered through `Router.page(...)`
+- `client/pages/**`: SSR page entrypoints registered through `Router.page(path, options, data, render)`
 - `server/controllers/**`: request handlers that extend `Controller`
 - `commands/**`: dev-only internal commands that extend `Commands`
 - `server/services/**`: business logic that extends `Service`
@@ -194,9 +194,11 @@ import Router from '@/client/router';
 
 Router.page(
   '/',
+  {
+    auth: false,
+    layout: false,
+  },
   ({ Plans, Stats }) => ({
-    _auth: false,
-    _layout: false,
     plans: Plans.getPlans(),
     stats: Stats.general(),
   }),
@@ -209,9 +211,10 @@ Router.page(
 What happens here:
 
 - the first argument is the route path
-- the optional setup function runs on the server for SSR data loading
-- keys prefixed with `_` become route options such as `_auth`, `_layout`, `_static`, or `_redirectLogged`
-- every other returned key becomes page data
+- the second argument is the explicit route-options object
+- the third argument is the page data function or `null`
+- route behavior such as `auth`, `layout`, `static`, or `redirectLogged` lives in the options object
+- every key returned from the data function becomes page data
 - the renderer receives the resolved data and the generated controller/service context
 
 ## Example: Controller
@@ -518,7 +521,7 @@ If you are an LLM or automation agent, start here:
 4. Read `.proteum/manifest.json` or run `proteum explain --json`.
 5. Inspect `server/controllers/**` for request entrypoints.
 6. Inspect `server/services/**` for business logic.
-7. Inspect `client/pages/**` for SSR routes and page setup contracts.
+7. Inspect `client/pages/**` for SSR routes and page data contracts.
 8. If the task touches a protected route or controller in dev and login UX is not the feature under test, use `proteum session <email> --role <role>` before Playwright or direct HTTP calls.
 
 For implementation rules in a real Proteum app, treat the local `AGENTS.md` files plus `proteum explain`, `proteum doctor`, `proteum diagnose`, `proteum perf`, and `proteum trace` as the task contract. This README is the framework overview, not the project-local instruction layer.

package/agents/project/AGENTS.md

@@ -136,14 +136,14 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 
 - Proteum scans page files for top-level `Router.page(...)` and `Router.error(...)` calls.
 - File path controls chunk identity and layout discovery; route path comes from the explicit `Router.page(...)` string.
-- Supported page signatures are `Router.page(path, render)`, `Router.page(path, setup, render)`, `Router.page(path, options, render)`, and `Router.page(path, options, setup, render)`.
-- For new work, prefer `Router.page(path, setup, render)` or `Router.page(path, options, setup, render)`.
-- `setup` returns one flat object. Reserved keys like `_auth`, `_layout`, `_static`, and `_redirectLogged` are route options; all other keys are SSR data.
-- Controller fetchers and promises returned from `setup` resolve before render.
-- `render` consumes resolved setup data and uses generated controller methods from render args or `@/client/context`.
-- Use `api.reload(...)` or `api.set(...)` only when intentionally mutating active page setup state.
+- The only supported page signature is `Router.page(path, options, data, render)`.
+- `options` is always required. `data` is the only nullable argument and must be `null` when the page has no SSR data loader.
+- `data` returns one flat object. Route-option keys such as `auth`, `layout`, `static`, and `_static` are forbidden in page data and must live in `options`.
+- Controller fetchers and promises returned from `data` resolve before render.
+- `render` consumes resolved page data and uses generated controller methods from render args or `@/client/context`.
+- Use `api.reload(...)` or `api.set(...)` only when intentionally mutating active page data state.
 - Error pages use `Router.error(code, options, render)` in `client/pages/_messages/**`.
-- Prefer `proteum create page ...` for new page boilerplate, then review the explicit route path and setup payload.
+- Prefer `proteum create page ...` for new page boilerplate, then review the explicit route path, options object, and data payload.
 
 ### Manual Routes
 

package/agents/project/CODING_STYLE.md

@@ -17,7 +17,7 @@ This file is the source of truth for codex coding style instructions in Proteum-
 - Keep short arrow functions and short returned object literals compact when they are easy to scan.
 - Keep JSX multiline only when it is clearly more readable; otherwise keep short JSX compact.
 - Avoid staircase formatting and unnecessary blank lines inside short callbacks.
-- Keep `Router.page(...)` and `Router.error(...)` registrations in the compact inline-call shape when possible, for example `Router.page('/path', setup, render);`.
+- Keep `Router.page(...)` and `Router.error(...)` registrations in the compact inline-call shape when possible, for example `Router.page('/path', {}, null, render);`.
 
 ## File organization
 

package/agents/project/client/AGENTS.md

@@ -3,7 +3,7 @@
 This is the canonical client-area contract for Proteum-based projects.
 Role: keep only client-area rules here.
 Keep here: client component, hook, design-system, accessibility, and client-context usage rules that apply beyond a single page.
-Do not put here: page `setup` and route-registration details, server/service rules, or generic project workflow already covered by broader ancestor `AGENTS.md` files.
+Do not put here: page `data` and route-registration details, server/service rules, or generic project workflow already covered by broader ancestor `AGENTS.md` files.
 
 Optimization source of truth: root-level `optimizations.md`.
 Diagnostics source of truth: root-level `diagnostics.md`.

package/agents/project/client/pages/AGENTS.md

@@ -2,7 +2,7 @@
 
 This is the canonical page-file contract for Proteum-based projects.
 Role: keep only page-file rules here.
-Keep here: `Router.page(...)` registration, SSR `setup` and `render` contracts, page payload shape, and page-local typing rules.
+Keep here: `Router.page(...)` registration, SSR `data` and `render` contracts, page payload shape, and page-local typing rules.
 Do not put here: generic component rules, server/service implementation details, or app-wide workflow already covered by broader AGENTS files.
 
 Optimization source of truth: root-level `optimizations.md`.
@@ -13,19 +13,19 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 
 - Proteum scans page files for top-level `Router.page(...)` and `Router.error(...)` calls.
 - File path controls chunk identity and layout discovery; route path comes from the explicit `Router.page(...)` string.
-- Supported page signatures are `Router.page(path, render)`, `Router.page(path, setup, render)`, `Router.page(path, options, render)`, and `Router.page(path, options, setup, render)`.
-- Prefer `Router.page(path, setup, render)` for normal SSR pages.
-- Use `Router.page(path, options, setup, render)` when a separate route-options object makes the call clearer.
+- The only supported page signature is `Router.page(path, options, data, render)`.
+- `options` is always required and must be an object.
+- `data` is the only nullable argument. Pass `null` when the page does not need SSR data.
 - Keep the `Router.page(...)` call compact instead of exploding each outer argument onto its own line.
 - Keep route registration at top level. Do not hide it behind helper abstractions.
 
-## Setup And Render
+## Data And Render
 
-- `setup` returns one flat object.
-- `_`-prefixed keys like `_auth`, `_layout`, `_static`, and `_redirectLogged` are route options.
-- Every other key is SSR data and should be consumed from `render`.
-- Controller fetchers and promises returned from `setup` resolve before render.
-- If a page needs route data, return it from `setup` and read it in `render`.
+- Route behavior belongs in the explicit `options` object, not in page data.
+- `data` returns one flat object or `null` is passed as the third argument when no page data is needed.
+- Returning route-option keys such as `auth`, `layout`, `static`, `redirectLogged`, or their `_`-prefixed variants from `data` is a contract error.
+- Controller fetchers and promises returned from `data` resolve before render.
+- If a page needs route data, return it from `data` and read it in `render`.
 
 ## Page Rules
 

package/agents/project/optimizations.md

@@ -22,12 +22,11 @@ When tradeoffs exist inside optimization work, optimize in this order:
 
 ## SSR And Page Size
 
-- SSR page data belongs in page `setup`, not in `api.fetch(...)`.
-- Prefer `Router.page(path, setup, render)` for normal SSR pages.
-- `setup` returns one flat object.
-- `_`-prefixed keys are route options. Every other key is SSR data and should be consumed from `render`.
-- If a page needs route data, return it from `setup` and read it in `render`.
-- Controller fetchers and promises returned from `setup` resolve before render.
+- SSR page data belongs in the explicit `Router.page(path, options, data, render)` `data` function, not in `api.fetch(...)`.
+- `options` carries route behavior. `data` returns one flat object or is `null` when the page has no SSR data loader.
+- Route-option keys and `_`-prefixed route-option aliases are forbidden in page data and must live in `options`.
+- If a page needs route data, return it from `data` and read it in `render`.
+- Controller fetchers and promises returned from `data` resolve before render.
 - Never use `api.fetch(...)` in page files for SSR loading.
 - Synchronous or SSR data calls must return only the strictly necessary data for the current render path to minimize SSR payload size.
 - If an existing controller or data method returns a broader shape than the SSR path needs, create a dedicated proxy controller method with a narrower typed contract instead of reusing the oversized payload.

package/agents/project/root/AGENTS.md

@@ -128,14 +128,14 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 
 - Proteum scans page files for top-level `Router.page(...)` and `Router.error(...)` calls.
 - File path controls chunk identity and layout discovery; route path comes from the explicit `Router.page(...)` string.
-- Supported page signatures are `Router.page(path, render)`, `Router.page(path, setup, render)`, `Router.page(path, options, render)`, and `Router.page(path, options, setup, render)`.
-- For new work, prefer `Router.page(path, setup, render)` or `Router.page(path, options, setup, render)`.
-- `setup` returns one flat object. Reserved keys like `_auth`, `_layout`, `_static`, and `_redirectLogged` are route options; all other keys are SSR data.
-- Controller fetchers and promises returned from `setup` resolve before render.
-- `render` consumes resolved setup data and uses generated controller methods from render args or `@/client/context`.
-- Use `api.reload(...)` or `api.set(...)` only when intentionally mutating active page setup state.
+- The only supported page signature is `Router.page(path, options, data, render)`.
+- `options` is always required. `data` is the only nullable argument and must be `null` when the page has no SSR data loader.
+- `data` returns one flat object. Route-option keys such as `auth`, `layout`, `static`, and `_static` are forbidden in page data and must live in `options`.
+- Controller fetchers and promises returned from `data` resolve before render.
+- `render` consumes resolved page data and uses generated controller methods from render args or `@/client/context`.
+- Use `api.reload(...)` or `api.set(...)` only when intentionally mutating active page data state.
 - Error pages use `Router.error(code, options, render)` in `client/pages/_messages/**`.
-- Prefer `proteum create page ...` for new page boilerplate, then review the explicit route path and setup payload.
+- Prefer `proteum create page ...` for new page boilerplate, then review the explicit route path, options object, and data payload.
 
 ### Manual Routes
 

package/cli/commands/migrate.ts

@@ -0,0 +1,51 @@
+import path from 'path';
+
+import cli from '..';
+import { runPageContractMigration } from '../migrate/pageContract';
+
+const printHuman = (summary: ReturnType<typeof runPageContractMigration>) => {
+    console.log(`Proteum migrate page-contract`);
+    console.log(`App root: ${summary.appRoot}`);
+    console.log(`Scanned files: ${summary.scannedFiles}`);
+    console.log(`Changed files: ${summary.changedFiles.length}${summary.dryRun ? ' (dry run)' : ''}`);
+
+    if (summary.changedFiles.length > 0) {
+        console.log('');
+        console.log('Rewritten files:');
+        for (const filepath of summary.changedFiles) {
+            console.log(`- ${path.relative(summary.appRoot, filepath)}`);
+        }
+    }
+
+    if (summary.manualFixes.length > 0) {
+        console.log('');
+        console.log('Manual fixes required:');
+        for (const fix of summary.manualFixes) {
+            console.log(
+                `- ${path.relative(summary.appRoot, fix.filepath)}:${fix.line}:${fix.column} ${fix.routeLabel} :: ${fix.reason}`,
+            );
+        }
+    }
+};
+
+export const run = async (): Promise<void> => {
+    const action = String(cli.args.action || '').trim();
+    if (action !== 'page-contract') {
+        throw new Error(`Unsupported migrate action "${action}". Expected "page-contract".`);
+    }
+
+    const summary = runPageContractMigration({
+        appRoot: String(cli.args.workdir || process.cwd()),
+        dryRun: cli.args.dryRun === true,
+    });
+
+    if (cli.args.json === true) {
+        console.log(JSON.stringify(summary, null, 2));
+    } else {
+        printHuman(summary);
+    }
+
+    if (summary.manualFixes.length > 0) {
+        throw new Error(`Page-contract migration requires manual fixes in ${summary.manualFixes.length} location(s).`);
+    }
+};

package/cli/compiler/artifacts/manifest.ts

@@ -4,7 +4,7 @@ import path from 'path';
 import app from '../../app';
 import cli from '../..';
 import { inspectProteumEnv } from '../../../common/env/proteumEnv';
-import { reservedRouteSetupKeys, routeSetupOptionKeys } from '../../../common/router/pageSetup';
+import { reservedRouteOptionKeys, routeOptionKeys } from '../../../common/router/pageData';
 import { getProjectInstructionGitignoreEntries } from '../../utils/agents';
 import {
     TProteumManifest,
@@ -303,7 +303,7 @@ export const writeCurrentProteumManifest = ({
         });
 
     const manifest: TProteumManifest = {
-        version: 9,
+        version: 10,
         app: {
             root: normalizeAbsolutePath(app.paths.root),
             coreRoot: normalizeAbsolutePath(cli.paths.core.root),
@@ -338,8 +338,8 @@ export const writeCurrentProteumManifest = ({
             },
         },
         conventions: {
-            routeSetupOptionKeys: [...routeSetupOptionKeys],
-            reservedRouteSetupKeys: [...reservedRouteSetupKeys],
+            routeOptionKeys: [...routeOptionKeys],
+            reservedRouteOptionKeys: [...reservedRouteOptionKeys],
         },
         env: {
             source: 'process.env',

package/cli/compiler/artifacts/routing.ts

@@ -59,7 +59,7 @@ const buildClientRouteManifestEntry = (filepath: string): TProteumManifestRoute
         invalidOptionKeys: definition.invalidOptionKeys,
         reservedOptionKeys: definition.reservedOptionKeys,
         optionsRaw: definition.optionsRaw,
-        hasSetup: definition.hasSetup,
+        hasData: definition.hasData,
         chunkId: pageChunk.chunkId,
         chunkFilepath: normalizePath(pageChunk.filepath),
         scope: 'app',
@@ -83,7 +83,7 @@ const buildServerRouteManifestEntries = (filepath: string) =>
         invalidOptionKeys: definition.invalidOptionKeys,
         reservedOptionKeys: definition.reservedOptionKeys,
         optionsRaw: definition.optionsRaw,
-        hasSetup: definition.hasSetup,
+        hasData: definition.hasData,
         scope: 'app',
     }));
 

package/cli/compiler/common/generatedRouteModules.ts

@@ -2,7 +2,7 @@ import fs from 'fs-extra';
 import path from 'path';
 import ts from 'typescript';
 
-import { getRouteSetupOptionKey } from '../../../common/router/pageSetup';
+import { getRouteOptionKey } from '../../../common/router/pageData';
 import writeIfChanged from '../writeIfChanged';
 
 type TRouteSide = 'client' | 'server';
@@ -33,7 +33,7 @@ export type TIndexedRouteDefinition = {
     invalidOptionKeys: string[];
     reservedOptionKeys: string[];
     optionsRaw?: string;
-    hasSetup: boolean;
+    hasData: boolean;
 };
 
 type TGeneratedClientRouteModuleOptions = { chunkId: string };
@@ -206,7 +206,7 @@ const getRouteOptionMetadata = (node: ts.ObjectLiteralExpression | undefined) =>
 
     for (const optionKey of optionKeys) {
         try {
-            const normalizedOptionKey = getRouteSetupOptionKey(optionKey);
+            const normalizedOptionKey = getRouteOptionKey(optionKey);
 
             if (normalizedOptionKey) {
                 normalizedOptionKeys.push(normalizedOptionKey);
@@ -438,29 +438,33 @@ const buildDestructuring = (importedServices: TImportedService[]) => {
 const getClientRouteSignature = (sourceFile: ts.SourceFile, definition: TRouteDefinition) => {
     const [, ...routeArgs] = [...definition.args];
 
-    if (routeArgs.length === 1) {
-        return { hasSetup: false, renderArg: routeArgs[0] };
-    }
-
-    if (routeArgs.length === 2) {
-        if (ts.isObjectLiteralExpression(routeArgs[0])) {
-            return { hasSetup: false, optionsArg: routeArgs[0], renderArg: routeArgs[1] };
+    if (definition.methodName === 'error') {
+        if (routeArgs.length === 2) {
+            return {
+                hasData: false,
+                optionsExpression: routeArgs[0],
+                optionsArg: ts.isObjectLiteralExpression(routeArgs[0]) ? routeArgs[0] : undefined,
+                renderArg: routeArgs[1],
+            };
         }
 
-        return { hasSetup: true, setupArg: routeArgs[0], renderArg: routeArgs[1] };
+        throw new Error(
+            `Unsupported client error route signature in ${sourceFile.fileName}. Expected Router.error(code, options, render).`,
+        );
     }
 
-    if (routeArgs.length === 3 && ts.isObjectLiteralExpression(routeArgs[0])) {
+    if (routeArgs.length === 3) {
         return {
-            hasSetup: true,
-            optionsArg: routeArgs[0],
-            setupArg: routeArgs[1],
+            hasData: routeArgs[1].kind !== ts.SyntaxKind.NullKeyword,
+            optionsExpression: routeArgs[0],
+            optionsArg: ts.isObjectLiteralExpression(routeArgs[0]) ? routeArgs[0] : undefined,
+            dataArg: routeArgs[1],
             renderArg: routeArgs[2],
         };
     }
 
     throw new Error(
-        `Unsupported client route signature in ${sourceFile.fileName}. Expected Router.page/error with 2-4 arguments.`,
+        `Unsupported client page route signature in ${sourceFile.fileName}. Expected Router.page(path, options, data, render).`,
     );
 };
 
@@ -469,30 +473,23 @@ const buildClientRegisterArgs = (
     definition: TRouteDefinition,
     clientRoute: TGeneratedClientRouteModuleOptions,
 ) => {
-    const { optionsArg, setupArg, renderArg } = getClientRouteSignature(sourceFile, definition);
+    const { optionsExpression, renderArg } = getClientRouteSignature(sourceFile, definition);
     const sourceLocation = getNodeLocation(sourceFile, definition.callExpression);
     const injectedOptions = buildInjectedRouteMetadata(sourceFile.fileName, sourceLocation, [
         `id: ${JSON.stringify(clientRoute.chunkId)}`,
     ]);
 
-    if (!optionsArg && !setupArg) {
-        return [injectedOptions, getNodeText(sourceFile, renderArg)];
-    }
-
-    if (optionsArg && !setupArg) {
+    if (definition.methodName === 'error') {
         return [
-            `{ ...(${getNodeText(sourceFile, optionsArg)}), ...${injectedOptions} }`,
+            `{ ...(${getNodeText(sourceFile, optionsExpression)}), ...${injectedOptions} }`,
             getNodeText(sourceFile, renderArg),
         ];
     }
 
-    if (!optionsArg && setupArg) {
-        return [injectedOptions, getNodeText(sourceFile, setupArg), getNodeText(sourceFile, renderArg)];
-    }
-
+    const { dataArg } = getClientRouteSignature(sourceFile, definition);
     return [
-        `{ ...(${getNodeText(sourceFile, optionsArg!)}), ...${injectedOptions} }`,
-        getNodeText(sourceFile, setupArg!),
+        `{ ...(${getNodeText(sourceFile, optionsExpression)}), ...${injectedOptions} }`,
+        getNodeText(sourceFile, dataArg!),
         getNodeText(sourceFile, renderArg),
     ];
 };
@@ -604,10 +601,8 @@ export const indexRouteDefinitions = ({ side, sourceFilepath }: { side: TRouteSi
                       normalizedOptionKeys: optionMetadata.normalizedOptionKeys,
                       invalidOptionKeys: optionMetadata.invalidOptionKeys,
                       reservedOptionKeys: optionMetadata.reservedOptionKeys,
-                      optionsRaw: clientSignature.optionsArg
-                          ? getNodeText(sourceFile, clientSignature.optionsArg)
-                          : undefined,
-                      hasSetup: clientSignature.hasSetup,
+                      optionsRaw: getNodeText(sourceFile, clientSignature.optionsExpression),
+                      hasData: false,
                   }
                 : {
                       methodName: definition.methodName,
@@ -627,10 +622,8 @@ export const indexRouteDefinitions = ({ side, sourceFilepath }: { side: TRouteSi
                       normalizedOptionKeys: optionMetadata.normalizedOptionKeys,
                       invalidOptionKeys: optionMetadata.invalidOptionKeys,
                       reservedOptionKeys: optionMetadata.reservedOptionKeys,
-                      optionsRaw: clientSignature.optionsArg
-                          ? getNodeText(sourceFile, clientSignature.optionsArg)
-                          : undefined,
-                      hasSetup: clientSignature.hasSetup,
+                      optionsRaw: getNodeText(sourceFile, clientSignature.optionsExpression),
+                      hasData: clientSignature.hasData,
                   };
         }
 
@@ -659,7 +652,7 @@ export const indexRouteDefinitions = ({ side, sourceFilepath }: { side: TRouteSi
             invalidOptionKeys: optionMetadata.invalidOptionKeys,
             reservedOptionKeys: optionMetadata.reservedOptionKeys,
             optionsRaw: optionsArg ? getNodeText(sourceFile, optionsArg) : undefined,
-            hasSetup: false,
+            hasData: false,
         };
     });
 };

package/cli/context.ts

@@ -27,7 +27,7 @@ export class CLIContext {
         const workdir =
             typeof args.workdir === 'string' && args.workdir.trim().length > 0 ? args.workdir.trim() : process.cwd();
 
-        this.args = { workdir, ...args, workdir };
+        this.args = { ...args, workdir };
         this.paths = new Paths(workdir, this.paths.core.root);
         this.paths.applyAliases();
         this.verbose = this.args.verbose === true;