proteum 2.4.3 → 2.5.0

package/cli/scaffold/templates.ts

@@ -22,19 +22,19 @@ export const createPageTemplate = ({
     routePath: string;
     heading: string;
     message: string;
-}) => `import Router from '@/client/router';
+}) => `import { definePageRoute } from '@common/router/definitions';
 
-Router.page(
-    ${JSON.stringify(routePath)},
-    {
+export default definePageRoute({
+    path: ${JSON.stringify(routePath)},
+    options: {
         auth: false,
         layout: false,
     },
-    () => ({
+    data: () => ({
         heading: ${JSON.stringify(heading)},
         message: ${JSON.stringify(message)},
     }),
-    ({ heading, message }) => {
+    render: ({ heading, message }) => {
         return (
             <main>
                 <h1>{heading}</h1>
@@ -42,7 +42,7 @@ Router.page(
             </main>
         );
     },
-);
+});
 `;
 
 export const createControllerTemplate = ({
@@ -53,15 +53,19 @@ export const createControllerTemplate = ({
     appIdentifier: string;
     className: string;
     methodName: string;
-}) => `import Controller from '@server/app/controller';
-
-export default class ${className} extends Controller<${appIdentifier}> {
-    public async ${methodName}() {
-        return {
-            ok: true,
-        };
-    }
-}
+}) => `import { defineAction, defineController } from '@server/app/controller';
+
+export default defineController({
+    actions: {
+        ${methodName}: defineAction({
+            async handler() {
+                return {
+                    ok: true,
+                };
+            },
+        }),
+    },
+});
 `;
 
 export const createCommandTemplate = ({
@@ -89,12 +93,17 @@ export const createRouteTemplate = ({
 }: {
     httpMethod: string;
     routePath: string;
-}) => `import { Router } from '@app';
+}) => `import { defineServerRoute } from '@common/router/definitions';
 
-Router.${httpMethod}(${JSON.stringify(routePath)}, {}, async () => {
-    return {
-        ok: true,
-    };
+export default defineServerRoute({
+    method: ${JSON.stringify(httpMethod.toUpperCase())},
+    path: ${JSON.stringify(routePath)},
+    options: {},
+    async handler() {
+        return {
+            ok: true,
+        };
+    },
 });
 `;
 
@@ -156,24 +165,26 @@ export const routerBaseConfig = {
 } satisfies RouterBaseConfig;
 `;
 
-export const createServerIndexTemplate = ({ appIdentifier }: { appIdentifier: string }) => `import { Application } from '@server/app';
+export const createServerIndexTemplate = (_args: { appIdentifier: string }) => `import { defineApplication } from '@server/app';
 import Router from '@server/services/router';
 import SchemaRouter from '@server/services/schema/router';
 
 import * as appConfig from '@/server/config/app';
 
-export default class ${appIdentifier} extends Application {
-    public Router = new Router(
-        this,
-        {
-            ...appConfig.routerBaseConfig,
-            plugins: {
-                schema: new SchemaRouter({}, this),
+export default defineApplication({
+    services: (app) => ({
+        Router: new Router(
+            app,
+            {
+                ...appConfig.routerBaseConfig,
+                plugins: {
+                    schema: new SchemaRouter({}, app),
+                },
             },
-        },
-        this,
-    );
-}
+            app,
+        ),
+    }),
+});
 `;
 
 export const createClientTsconfigTemplate = (paths: TTsconfigTemplatePaths) => `{

package/cli/utils/agents.ts

@@ -638,19 +638,32 @@ function renderEmbeddedProjectInstructions({ appRoot, coreRoot, includeMonorepoR
         '- Do not run `git restore` or `git reset`.',
         '- Keep `proteum dev` sessions tracked with explicit session files and do not replace another live session.',
         '',
+        '## Explicit App-Building Contract',
+        '',
+        '- App roots default-export `defineApplication({ services, router, models, commands })`; `server/index.ts` is the canonical type root for the project app, services, router plugins, request context, and models.',
+        '- Client page files default-export `definePageRoute({ path, options, data, render })` or `defineErrorRoute({ code, options, render })`; route paths come from the definition object, not from `Router.page(...)` or the file path.',
+        '- Manual HTTP route files default-export `defineServerRoute({ method, path, options, handler })` or `defineServerRoutes(...)`; use `expressHandler(...)` only when raw Express `req`, `res`, or `next` is required.',
+        '- Controllers default-export `defineController({ path, actions })`; actions use `defineAction({ input, handler })`, and parsed input is read from the handler context.',
+        '- Never import `@app` in page, route, or controller files. Never call top-level `Router.page(...)`, `Router.error(...)`, `Router.get(...)`, `Router.post(...)`, `Router.put(...)`, `Router.patch(...)`, `Router.delete(...)`, or `Router.express(...)` in app source.',
+        '- Runtime app, service, request, response, router, auth, and custom router-plugin access belongs only in typed callback parameters such as `data`, `render`, route `handler`, controller action `handler`, `defineServerRoutes((app) => ...)`, or typed service `this.app`/`this.services`.',
+        '',
         '## Triggered Instruction Reads',
         '',
         'Keep this root file as a router. MCP-selected previews are enough for read-only discovery and diagnostics. Read the referenced full instruction file only before edits or git writes, when `fullRead`/`fullReadPolicy` requires it, or when the preview is insufficient.',
         '',
+        '- Worktree Preflight (`cwd` inside `/.codex/worktrees/`, newly created Proteum worktree, or before editing in a Codex worktree): read Root contract fallback, run `npx proteum worktree init --source <source-app-root>` when the bootstrap marker is missing, run `npx proteum worktree init --source <source-app-root> --refresh` when Proteum reports stale bootstrap state, use `--skip-deps --reason "..."` only for intentional dependency skips, then run `npx proteum runtime status`; for runtime-visible work start or reuse one tracked `npx proteum dev` session using the Task Lifecycle launch workflow.',
         '- Git lifecycle (`commit`, `and commit`, `stage`, `push`, `PR`, pull request): read Root contract fallback before any git write.',
-        '- Before finishing production code changes: read Root contract fallback, `CODING_STYLE.md`, `tests/AGENTS.md`, and any touched area `AGENTS.md`.',
+        '- Before git writes after a bug fix, behavior change, decision change, or docs-relevant production change: read `DOCUMENTATION.md` and verify required docs, fix notes, or ADRs were updated or explicitly skipped with a reason.',
+        '- Before finishing production code changes: read Root contract fallback, `DOCUMENTATION.md`, `CODING_STYLE.md`, `tests/AGENTS.md`, and any touched area `AGENTS.md`.',
         '- Runtime-visible, request-time, router, SSR, browser, or controller behavior: read Root contract fallback and `diagnostics.md` for verification routing.',
+        '- Bug fixes, regressions, incidents, broken public routes, auth/OAuth failures, integration failures, or production behavior fixes: read `DOCUMENTATION.md` before editing and update the relevant fix/regression docs when required.',
         '- Non-trivial feature, product, business-rule, UX, copy, or docs changes: read `DOCUMENTATION.md` before editing.',
         '- Implementation edits: read `CODING_STYLE.md` before editing, plus the matching area file from the routing table.',
         '',
         '## Routing Table',
         '',
         '- Non-trivial coding tasks, feature docs, product intent, acceptance criteria, or docs updates: read `DOCUMENTATION.md`.',
+        '- Bug fixes, regressions, incidents, broken public routes, auth/OAuth failures, integration failures, or production behavior fixes: read `DOCUMENTATION.md`, `diagnostics.md`, `CODING_STYLE.md`, `tests/AGENTS.md`, and the touched area `AGENTS.md`; update or create `docs/fixes/YYYY-MM-DD-short-bug-name.md` and regression-test docs when required, or explain why no docs update was needed.',
         '- GEO/SEO/crawler/structured-data/AI-source changes: read `DOCUMENTATION.md`, `CODING_STYLE.md`, `tests/AGENTS.md`, and update or create a docs page under `docs/` describing the public contract, routes, validation, and operational caveats.',
         '- Raw errors, failing requests, traces, perf, or reproduction: read `diagnostics.md`.',
         '- Implementation edits: read `CODING_STYLE.md` before editing.',

package/client/services/router/index.tsx

@@ -21,8 +21,11 @@ import BaseRouter, {
     TErrorRoute,
     TRouteOptions,
     TRouteModule,
+    type TRouteDefinition,
+    type TRouteMetadata,
     matchRoute,
     buildUrl,
+    withRouteMetadata,
 } from '@common/router';
 import type { TRegisterPageArgs, TSsrUnresolvedRoute } from '@common/router/contracts';
 import { getLayout } from '@common/router/layouts';
@@ -241,14 +244,31 @@ export default class ClientRouter<
         return currentRoute;
     }
 
-    public page<TProvidedData extends {} = {}>(
+    public registerRouteDefinition(definition: TRouteDefinition, metadata: TRouteMetadata = {}) {
+        if (definition.kind === 'page') {
+            return this.page(
+                definition.path,
+                withRouteMetadata(definition.options, metadata),
+                definition.data,
+                definition.render,
+            );
+        }
+
+        if (definition.kind === 'error') {
+            return this.error(definition.code, withRouteMetadata(definition.options, metadata), definition.render);
+        }
+
+        throw new Error(`Client router cannot register server route definition: ${definition.method} ${definition.path}`);
+    }
+
+    protected page<TProvidedData extends {} = {}>(
         path: string,
         options: Partial<TRouteOptions>,
         data: TPageDataProvider<TProvidedData> | null,
         renderer: TFrontRenderer<TProvidedData>,
     ): TClientPageRoute<this>;
 
-    public page(...args: TRegisterPageArgs<any, TRouteOptions>): TClientPageRoute<this> {
+    protected page(...args: TRegisterPageArgs<any, TRouteOptions>): TClientPageRoute<this> {
         const { path, options, data, renderer, layout } = getRegisterPageArgs(...args);
 
         // Page ids are injected by the generated route wrapper modules.
@@ -272,7 +292,7 @@ export default class ClientRouter<
         return route;
     }
 
-    public error(
+    protected error(
         code: number,
         options: Partial<TRouteOptions>,
         renderer: TFrontRenderer<{}, { message: string }>,

package/client/services/router/request/api.ts

@@ -38,8 +38,19 @@ type TExecuteResult<TData> = { data: TData; durationMs: number; response: Respon
 
 export type Config = {};
 
-const isFileValue = (value: unknown): value is File =>
-    typeof File !== 'undefined' && typeof value === 'object' && value instanceof File;
+const isFileValue = (value: unknown): value is Blob =>
+    typeof Blob !== 'undefined' && typeof value === 'object' && value instanceof Blob;
+
+const isFileListValue = (value: unknown): value is FileList =>
+    typeof FileList !== 'undefined' && typeof value === 'object' && value instanceof FileList;
+
+const containsFileValue = (value: unknown): boolean => {
+    if (isFileValue(value) || isFileListValue(value)) return true;
+    if (value instanceof Date) return false;
+    if (Array.isArray(value)) return value.some((item) => containsFileValue(item));
+    if (value && typeof value === 'object') return Object.values(value).some((item) => containsFileValue(item));
+    return false;
+};
 
 /*----------------------------------
 - FUNCTION
@@ -286,8 +297,7 @@ export default class ApiClient implements ApiClientService {
         // Update options depending on data
         if (data) {
             // If file included in data, need to use multipart
-            // TODO: deep check
-                const hasFile = Object.values(data).some((value) => isFileValue(value));
+            const hasFile = containsFileValue(data);
             if (hasFile) {
                 // GET request = Can't send files
                 if (method === 'GET') throw new Error('Cannot send file in GET request');

package/common/dev/contractsDoctor.ts

@@ -314,7 +314,7 @@ const buildHookContractDiagnostics = (manifest: TProteumManifest, sourceFilepath
                                     sourceLocation,
                                     fixHint:
                                         importedHook.kind === 'router-context'
-                                            ? 'Call the hook only inside a Router.page render callback, a component rendered under App, or a custom hook used from that tree.'
+                                            ? 'Call the hook only inside a definePageRoute render callback, a component rendered under App, or a custom hook used from that tree.'
                                             : 'Move the hook back under the provider-managed React tree or pass the required values as explicit props or SSR data.',
                                     relatedFilepaths,
                                 }),

package/common/dev/mcpPayloads.ts

@@ -131,6 +131,10 @@ export const resolveTriggeredInstructionReads = ({
         normalizedQuery,
         /\b(implement|change|edit|update|modify|fix|add|remove|refactor|increase|decrease|code)\b/,
     );
+    const looksLikeBugFixOrDecisionDocs = matchesInstructionTrigger(
+        normalizedQuery,
+        /\b(bug|regression|incident|broken|outage|fix|fixed|decision|adr|auth|oauth|integration|public route|production behavior)\b/,
+    );
     const looksLikeProductOrDocs = matchesInstructionTrigger(
         normalizedQuery,
         /\b(feature|product|business|acceptance|docs|documentation|ux|copy|onboarding|pricing|commercial|semantics)\b/,
@@ -153,6 +157,9 @@ export const resolveTriggeredInstructionReads = ({
     if (looksLikeImplementationEdit) {
         addRead(codingStyle, 'Implementation edit trigger; read coding style before editing.');
     }
+    if (looksLikeBugFixOrDecisionDocs) {
+        addRead(documentation, 'Bug fix, regression, auth/OAuth, integration, public-route, decision, or production-behavior trigger.');
+    }
     if (looksLikeProductOrDocs) {
         addRead(documentation, 'Feature, product, business-rule, UX, copy, or docs trigger.');
     }
@@ -903,7 +910,7 @@ export const resolveInstructionRouting = ({
 
     addReadWhen(
         'DOCUMENTATION.md',
-        'Read before non-trivial coding tasks to choose the smallest `/docs` pack and update docs after changes.',
+        'Read before non-trivial coding tasks, bug fixes, auth/OAuth, integration, public-route, decision, or production-behavior changes to choose the smallest `/docs` pack and update docs after changes.',
     );
     addReadWhen('diagnostics.md', 'Read for raw errors, failing requests, traces, perf regressions, or reproduction work.');
     addReadWhen('CODING_STYLE.md', 'Read before editing implementation files.');

package/common/env/proteumEnv.ts

@@ -238,6 +238,16 @@ const parseAbsoluteUrl = ({
     return value;
 };
 
+const applyRouterPortOverrideToUrl = (value: string, routerPortOverride: number | undefined) => {
+    if (routerPortOverride === undefined) return value;
+
+    const url = new URL(value);
+    url.port = String(routerPortOverride);
+    const serialized = url.toString();
+
+    return value.endsWith('/') ? serialized : serialized.replace(/\/$/, '');
+};
+
 const parseConnectedProjectAbsoluteUrl = ({
     appDir,
     namespace,
@@ -323,16 +333,18 @@ export const parseProteumEnvConfig = ({
         value: getRequiredEnvValue({ key: 'PORT', context }),
         context,
     });
-    const currentDomain = parseAbsoluteUrl({
+    const configuredCurrentDomain = parseAbsoluteUrl({
         key: 'URL',
         value: getRequiredEnvValue({ key: 'URL', context }),
         context,
     });
-    const internalUrl = parseAbsoluteUrl({
+    const configuredInternalUrl = parseAbsoluteUrl({
         key: 'URL_INTERNAL',
         value: getRequiredEnvValue({ key: 'URL_INTERNAL', context }),
         context,
     });
+    const currentDomain = applyRouterPortOverrideToUrl(configuredCurrentDomain, routerPortOverride);
+    const internalUrl = applyRouterPortOverrideToUrl(configuredInternalUrl, routerPortOverride);
 
     const traceEnable = parseBooleanEnvValue({
         key: 'TRACE_ENABLE',

package/common/router/contracts.ts

@@ -10,7 +10,7 @@ import type { TRouteOptions } from '.';
 - PUBLIC API
 ----------------------------------*/
 
-// Supported `Router.page(...)` registration signature shared by client and compiler code.
+// Runtime page registration signature used by generated definePageRoute wrappers.
 export type TRegisterPageArgs<TProvidedData extends {} = {}, TPageOptions extends {} = TRouteOptions> =
     [
         path: string,

package/common/router/definitions.ts

@@ -0,0 +1,177 @@
+/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+// Npm
+import type { Request, Response, NextFunction } from 'express';
+
+// Core
+import type { TAnyRouter, TRouterContext, TRouteHttpMethod } from '@server/services/router';
+import type { TFrontRenderer, TPageDataProvider } from './response/page';
+import type { TRouteOptions } from '.';
+
+/*----------------------------------
+- TYPES
+----------------------------------*/
+
+export type TRouteMetadata = {
+    filepath?: string;
+    sourceLocation?: { line: number; column: number };
+    id?: string;
+};
+
+export type TRouteDefinitionHttpMethod = TRouteHttpMethod | Lowercase<Exclude<TRouteHttpMethod, '*'>>;
+
+export type TPageRouteDefinition<TProvidedData extends {} = {}> = {
+    kind: 'page';
+    path: string;
+    options: Partial<TRouteOptions>;
+    data: TPageDataProvider<TProvidedData> | null;
+    render: TFrontRenderer<TProvidedData>;
+};
+
+export type TErrorRouteDefinition = {
+    kind: 'error';
+    code: number;
+    options: Partial<TRouteOptions>;
+    render: TFrontRenderer<{}, { message: string }>;
+};
+
+export type TServerRouteDefinition<TRouter extends TAnyRouter = TAnyRouter> = {
+    kind: 'server';
+    method: TRouteDefinitionHttpMethod;
+    path: string;
+    options: Partial<TRouteOptions>;
+    handler: (context: TRouterContext<TRouter>) => any;
+};
+
+export type TRouteDefinition =
+    | TPageRouteDefinition
+    | TErrorRouteDefinition
+    | TServerRouteDefinition;
+
+export type TServerRouteDefinitionsFactory<TApplication extends object = object> = (
+    app: TApplication,
+) => TServerRouteDefinition[];
+
+export type TRouteDefinitionExport =
+    | TRouteDefinition
+    | TRouteDefinition[]
+    | TServerRouteDefinitionsFactory<any>
+    | { default: TRouteDefinition | TRouteDefinition[] | TServerRouteDefinitionsFactory<any> };
+
+export type TExpressRouteHandler<TRouter extends TAnyRouter = TAnyRouter> = (
+    req: Request,
+    res: Response,
+    next: NextFunction,
+    requestContext: TRouterContext<TRouter>,
+) => void | Promise<void>;
+
+export type TRouteDefinitionRegistrar = {
+    registerRouteDefinition: (definition: TRouteDefinition, metadata?: TRouteMetadata) => unknown;
+};
+
+/*----------------------------------
+- HELPERS
+----------------------------------*/
+
+export const definePageRoute = <TProvidedData extends {} = {}>({
+    path,
+    options,
+    data,
+    render,
+}: Omit<TPageRouteDefinition<TProvidedData>, 'kind'>): TPageRouteDefinition<TProvidedData> => ({
+    kind: 'page',
+    path,
+    options,
+    data,
+    render,
+});
+
+export const defineErrorRoute = ({
+    code,
+    options,
+    render,
+}: Omit<TErrorRouteDefinition, 'kind'>): TErrorRouteDefinition => ({
+    kind: 'error',
+    code,
+    options,
+    render,
+});
+
+export const defineServerRoute = <TRouter extends TAnyRouter = TAnyRouter>({
+    method,
+    path,
+    options,
+    handler,
+}: Omit<TServerRouteDefinition<TRouter>, 'kind'>): TServerRouteDefinition<TRouter> => ({
+    kind: 'server',
+    method,
+    path,
+    options,
+    handler,
+});
+
+export const defineServerRoutes = <
+    TRouter extends TAnyRouter = TAnyRouter,
+    TApplication extends object = object,
+>(
+    routes: TServerRouteDefinition<TRouter>[] | TServerRouteDefinitionsFactory<TApplication>,
+) => routes;
+
+export const expressHandler = <TRouter extends TAnyRouter = TAnyRouter>(
+    middleware: TExpressRouteHandler<TRouter>,
+) => {
+    return (requestContext: TRouterContext<TRouter>) =>
+        new Promise((resolve, reject) => {
+            requestContext.request.res.on('finish', function () {
+                resolve(true);
+            });
+
+            try {
+                const result = middleware(
+                    requestContext.request.req,
+                    requestContext.request.res,
+                    () => {
+                        resolve(true);
+                    },
+                    requestContext,
+                );
+
+                if (result && typeof (result as Promise<void>).then === 'function') {
+                    (result as Promise<void>).catch(reject);
+                }
+            } catch (error) {
+                reject(error);
+            }
+        });
+};
+
+export const normalizeRouteDefinitions = (
+    value: TRouteDefinition | TRouteDefinition[] | TServerRouteDefinitionsFactory<any>,
+    app?: object,
+) => {
+    const definitions = typeof value === 'function' ? value(app || {}) : value;
+
+    return Array.isArray(definitions) ? definitions : [definitions];
+};
+
+export const withRouteMetadata = <TOptions extends Partial<TRouteOptions>>(
+    options: TOptions,
+    metadata: TRouteMetadata,
+): TOptions & TRouteMetadata => ({
+    ...options,
+    ...metadata,
+});
+
+export const registerRouteDefinition = (
+    router: TRouteDefinitionRegistrar,
+    definition: TRouteDefinition,
+    metadata: TRouteMetadata = {},
+) => {
+    if (!router || typeof router.registerRouteDefinition !== 'function') {
+        throw new Error('Proteum route definitions require a router with registerRouteDefinition(definition, metadata).');
+    }
+
+    return router.registerRouteDefinition(definition, metadata);
+};

package/common/router/index.ts

@@ -7,8 +7,6 @@ import type zod from 'zod';
 
 // types
 import type { default as ClientRouter, TRouterContext as ClientRouterContext } from '@client/services/router';
-import type { TRegisterPageArgs } from './contracts';
-
 import type { TAnyRouter, TRouterContext as ServerRouterContext, TRouteHttpMethod } from '@server/services/router';
 
 import type RouterRequest from './request';
@@ -18,13 +16,34 @@ import type { TAuthCheckInput, TAuthTrackingContext } from '@server/services/aut
 import type { TAppArrowFunction } from '@common/app';
 
 // Specfic
-import type { default as Page, TFrontRenderer, TPageDataProvider } from './response/page';
+import type { default as Page, TPageDataProvider } from './response/page';
 
 /*----------------------------------
 - TYPES: ROUTES
 ----------------------------------*/
 
 export type { Layout } from './layouts';
+export {
+    defineErrorRoute,
+    definePageRoute,
+    defineServerRoute,
+    defineServerRoutes,
+    expressHandler,
+    normalizeRouteDefinitions,
+    registerRouteDefinition,
+    withRouteMetadata,
+} from './definitions';
+export type {
+    TErrorRouteDefinition,
+    TExpressRouteHandler,
+    TPageRouteDefinition,
+    TRouteDefinition,
+    TRouteDefinitionExport,
+    TRouteDefinitionHttpMethod,
+    TRouteDefinitionRegistrar,
+    TRouteMetadata,
+    TServerRouteDefinition,
+} from './definitions';
 
 export type { default as Request } from './request';
 export type { default as Response } from './response';
@@ -166,13 +185,5 @@ export const matchRoute = (route: TRouteMatch, request: RouterRequest) => {
 ----------------------------------*/
 
 export default abstract class RouterInterface {
-    public abstract page<TControllerData extends TObjetDonnees = {}>(
-        ...args: TRegisterPageArgs<TControllerData, TRouteOptions>
-    ): unknown;
-
-    public abstract error(
-        code: number,
-        options: Partial<TRouteOptions>,
-        renderer: TFrontRenderer<{}, { message: string }>,
-    ): unknown;
+    public abstract registerRouteDefinition(definition: unknown, metadata?: unknown): unknown;
 }

package/common/router/pageData.ts

@@ -46,7 +46,7 @@ const formatRouteSource = (route: TAnyRoute) => {
 };
 
 export const getRouteOptionKey = (key: string) => {
-    if (reservedRouteOptionKeysSet.has(key)) throw new Error(`"${key}" is a reserved Router.page option key.`);
+    if (reservedRouteOptionKeysSet.has(key)) throw new Error(`"${key}" is a reserved route option key.`);
 
     return routeOptionKeysSet.has(key) ? (key as keyof TRouteOptions) : null;
 };
@@ -54,8 +54,8 @@ export const getRouteOptionKey = (key: string) => {
 export const validatePageDataResult = (route: TAnyRoute, result: unknown) => {
     if (!result || typeof result !== 'object' || Array.isArray(result)) {
         throw new Error(
-            `Router.page data for ${formatRouteTarget(route)} in ${formatRouteSource(route)} must return an object. ` +
-                `If the page has no data loader, pass null as the third argument.`,
+            `definePageRoute data for ${formatRouteTarget(route)} in ${formatRouteSource(route)} must return an object. ` +
+                `If the page has no data loader, set data to null.`,
         );
     }
 
@@ -63,8 +63,8 @@ export const validatePageDataResult = (route: TAnyRoute, result: unknown) => {
         if (!reservedPageDataKeys.has(key)) continue;
 
         throw new Error(
-            `Router.page data for ${formatRouteTarget(route)} in ${formatRouteSource(route)} cannot return reserved key "${key}". ` +
-                `Move route behavior into the explicit Router.page(path, options, data, render) options argument.`,
+            `definePageRoute data for ${formatRouteTarget(route)} in ${formatRouteSource(route)} cannot return reserved key "${key}". ` +
+                `Move route behavior into definePageRoute({ path, options, data, render }).options.`,
         );
     }
 

package/common/router/register.ts

@@ -21,12 +21,12 @@ export const getRegisterPageArgs = (...args: TRegisterPageArgs<any, TRouteOption
     const [path, options, data, renderer] = args;
 
     if (!options || typeof options !== 'object' || Array.isArray(options)) {
-        throw new Error(`Router.page(${JSON.stringify(path)}) requires an explicit options object as its second argument.`);
+        throw new Error(`definePageRoute(${JSON.stringify(path)}) requires an explicit options object.`);
     }
 
     if (data !== null && typeof data !== 'function') {
         throw new Error(
-            `Router.page(${JSON.stringify(path)}) requires a data function or null as its third argument.`,
+            `definePageRoute(${JSON.stringify(path)}) requires a data function or null.`,
         );
     }
 

package/common/router/request/api.ts

@@ -43,9 +43,19 @@ export type TApiFetchOptions = {
 
 export type TPostData = TPostDataWithFile;
 
-export type TPostDataWithFile = { [key: string]: PrimitiveValue };
+export type TPostDataJsonValue =
+    | PrimitiveValue
+    | null
+    | undefined
+    | Date
+    | TPostDataJsonValue[]
+    | { [key: string]: TPostDataJsonValue };
 
-export type TPostDataWithoutFile = { [key: string]: PrimitiveValue };
+export type TPostDataValue = TPostDataJsonValue | Blob | FileList;
+
+export type TPostDataWithFile = { [key: string]: TPostDataValue };
+
+export type TPostDataWithoutFile = { [key: string]: TPostDataJsonValue };
 
 export type TDataReturnedByFetchers<TProvidedData extends TFetcherList = {}> = {
     [Property in keyof TProvidedData]: ThenArg<TProvidedData[Property]>;