@webstir-io/module-contract 0.1.69 → 0.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Electric Coding LLC and contributors
+Copyright (c) 2025-2026 Sqware Logics, LLC and contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/client-nav.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The wire protocol between the client-nav feature and the backend runtime. Constants only, so a
+ * browser bundle can import them without the rest of the contract.
+ */
+export declare const CLIENT_NAV_HEADERS: {
+    /** Sent on every request client-nav makes itself. */
+    readonly request: 'x-webstir-client-nav';
+    /**
+     * Sent when client-nav can follow a redirect itself: the backend then answers a redirect with
+     * 204 and `location` instead of 3xx, so the destination keeps its #fragment.
+     */
+    readonly acceptLocation: 'x-webstir-accept-location';
+    /** Where to go next, in place of a redirect's Location. */
+    readonly location: 'x-webstir-location';
+    /** Identifies one form submission, so the same post sent again gets the first answer. */
+    readonly submission: 'x-webstir-submission';
+};
+/** The form field carrying the submission id when client-nav falls back to a normal post. */
+export declare const CLIENT_NAV_SUBMISSION_FIELD = "_webstir_submission";

package/dist/client-nav.js

@@ -0,0 +1,19 @@
+/**
+ * The wire protocol between the client-nav feature and the backend runtime. Constants only, so a
+ * browser bundle can import them without the rest of the contract.
+ */
+export const CLIENT_NAV_HEADERS = {
+    /** Sent on every request client-nav makes itself. */
+    request: 'x-webstir-client-nav',
+    /**
+     * Sent when client-nav can follow a redirect itself: the backend then answers a redirect with
+     * 204 and `location` instead of 3xx, so the destination keeps its #fragment.
+     */
+    acceptLocation: 'x-webstir-accept-location',
+    /** Where to go next, in place of a redirect's Location. */
+    location: 'x-webstir-location',
+    /** Identifies one form submission, so the same post sent again gets the first answer. */
+    submission: 'x-webstir-submission',
+};
+/** The form field carrying the submission id when client-nav falls back to a normal post. */
+export const CLIENT_NAV_SUBMISSION_FIELD = '_webstir_submission';

package/dist/index.d.ts

@@ -85,6 +85,24 @@ export interface RequestContext<TRequest = unknown, TReply = unknown, TAuth = un
     readonly requestId: string;
     readonly now: () => Date;
 }
+export type FormIssueCode = 'validation' | 'auth' | 'csrf';
+export interface FormIssue {
+    readonly code?: FormIssueCode;
+    readonly field?: string;
+    readonly message: string;
+}
+export type FormValues = Readonly<Record<string, string | string[]>>;
+/** A form's last failed submission, as a view loader reads it. Empty when there is none. */
+export interface FormState {
+    readonly submitted: boolean;
+    readonly values: FormValues;
+    readonly issues: readonly FormIssue[];
+    /** The first message per field, plus `form` for issues without a field. */
+    readonly errors: Readonly<Record<string, string>>;
+}
+export interface FormStateReader {
+    read(formId: string): FormState;
+}
 export interface SSRContext<TParams = Record<string, string>, TAuth = unknown, TSession = unknown, TEnv extends EnvAccessor = EnvAccessor, TLogger extends Logger = Logger> {
     readonly url: URL;
     readonly params: TParams;
@@ -96,6 +114,7 @@ export interface SSRContext<TParams = Record<string, string>, TAuth = unknown, T
     readonly logger: TLogger;
     readonly requestId?: string;
     readonly now: () => Date;
+    readonly forms: FormStateReader;
 }
 export interface AuthSession<TData = Record<string, unknown>> {
     readonly id: string;
@@ -353,14 +372,17 @@ export type FlashPublishCondition = z.infer<typeof flashPublishConditionSchema>;
 export declare const routeFlashMessageSchema: z.ZodObject<{
     key: z.ZodString;
     level: z.ZodOptional<z.ZodEnum<["info", "success", "warning", "error"]>>;
+    message: z.ZodOptional<z.ZodString>;
     when: z.ZodOptional<z.ZodEnum<["always", "success", "error"]>>;
 }, "strict", z.ZodTypeAny, {
     key: string;
     level?: "error" | "info" | "success" | "warning" | undefined;
+    message?: string | undefined;
     when?: "always" | "error" | "success" | undefined;
 }, {
     key: string;
     level?: "error" | "info" | "success" | "warning" | undefined;
+    message?: string | undefined;
     when?: "always" | "error" | "success" | undefined;
 }>;
 export type RouteFlashMessageDefinition = z.infer<typeof routeFlashMessageSchema>;
@@ -369,14 +391,17 @@ export declare const routeFlashSchema: z.ZodObject<{
     publish: z.ZodOptional<z.ZodArray<z.ZodObject<{
         key: z.ZodString;
         level: z.ZodOptional<z.ZodEnum<["info", "success", "warning", "error"]>>;
+        message: z.ZodOptional<z.ZodString>;
         when: z.ZodOptional<z.ZodEnum<["always", "success", "error"]>>;
     }, "strict", z.ZodTypeAny, {
         key: string;
         level?: "error" | "info" | "success" | "warning" | undefined;
+        message?: string | undefined;
         when?: "always" | "error" | "success" | undefined;
     }, {
         key: string;
         level?: "error" | "info" | "success" | "warning" | undefined;
+        message?: string | undefined;
         when?: "always" | "error" | "success" | undefined;
     }>, "many">>;
 }, "strict", z.ZodTypeAny, {
@@ -384,6 +409,7 @@ export declare const routeFlashSchema: z.ZodObject<{
     publish?: {
         key: string;
         level?: "error" | "info" | "success" | "warning" | undefined;
+        message?: string | undefined;
         when?: "always" | "error" | "success" | undefined;
     }[] | undefined;
 }, {
@@ -391,6 +417,7 @@ export declare const routeFlashSchema: z.ZodObject<{
     publish?: {
         key: string;
         level?: "error" | "info" | "success" | "warning" | undefined;
+        message?: string | undefined;
         when?: "always" | "error" | "success" | undefined;
     }[] | undefined;
 }>;
@@ -413,14 +440,17 @@ export declare const routeFormSchema: z.ZodObject<{
         publish: z.ZodOptional<z.ZodArray<z.ZodObject<{
             key: z.ZodString;
             level: z.ZodOptional<z.ZodEnum<["info", "success", "warning", "error"]>>;
+            message: z.ZodOptional<z.ZodString>;
             when: z.ZodOptional<z.ZodEnum<["always", "success", "error"]>>;
         }, "strict", z.ZodTypeAny, {
             key: string;
             level?: "error" | "info" | "success" | "warning" | undefined;
+            message?: string | undefined;
             when?: "always" | "error" | "success" | undefined;
         }, {
             key: string;
             level?: "error" | "info" | "success" | "warning" | undefined;
+            message?: string | undefined;
             when?: "always" | "error" | "success" | undefined;
         }>, "many">>;
     }, "strict", z.ZodTypeAny, {
@@ -428,6 +458,7 @@ export declare const routeFormSchema: z.ZodObject<{
         publish?: {
             key: string;
             level?: "error" | "info" | "success" | "warning" | undefined;
+            message?: string | undefined;
             when?: "always" | "error" | "success" | undefined;
         }[] | undefined;
     }, {
@@ -435,6 +466,7 @@ export declare const routeFormSchema: z.ZodObject<{
         publish?: {
             key: string;
             level?: "error" | "info" | "success" | "warning" | undefined;
+            message?: string | undefined;
             when?: "always" | "error" | "success" | undefined;
         }[] | undefined;
     }>>;
@@ -450,6 +482,7 @@ export declare const routeFormSchema: z.ZodObject<{
         publish?: {
             key: string;
             level?: "error" | "info" | "success" | "warning" | undefined;
+            message?: string | undefined;
             when?: "always" | "error" | "success" | undefined;
         }[] | undefined;
     } | undefined;
@@ -465,6 +498,7 @@ export declare const routeFormSchema: z.ZodObject<{
         publish?: {
             key: string;
             level?: "error" | "info" | "success" | "warning" | undefined;
+            message?: string | undefined;
             when?: "always" | "error" | "success" | undefined;
         }[] | undefined;
     } | undefined;
@@ -1579,14 +1613,17 @@ export declare const routeDefinitionSchema: z.ZodObject<{
         publish: z.ZodOptional<z.ZodArray<z.ZodObject<{
             key: z.ZodString;
             level: z.ZodOptional<z.ZodEnum<["info", "success", "warning", "error"]>>;
+            message: z.ZodOptional<z.ZodString>;
             when: z.ZodOptional<z.ZodEnum<["always", "success", "error"]>>;
         }, "strict", z.ZodTypeAny, {
             key: string;
             level?: "error" | "info" | "success" | "warning" | undefined;
+            message?: string | undefined;
             when?: "always" | "error" | "success" | undefined;
         }, {
             key: string;
             level?: "error" | "info" | "success" | "warning" | undefined;
+            message?: string | undefined;
             when?: "always" | "error" | "success" | undefined;
         }>, "many">>;
     }, "strict", z.ZodTypeAny, {
@@ -1594,6 +1631,7 @@ export declare const routeDefinitionSchema: z.ZodObject<{
         publish?: {
             key: string;
             level?: "error" | "info" | "success" | "warning" | undefined;
+            message?: string | undefined;
             when?: "always" | "error" | "success" | undefined;
         }[] | undefined;
     }, {
@@ -1601,6 +1639,7 @@ export declare const routeDefinitionSchema: z.ZodObject<{
         publish?: {
             key: string;
             level?: "error" | "info" | "success" | "warning" | undefined;
+            message?: string | undefined;
             when?: "always" | "error" | "success" | undefined;
         }[] | undefined;
     }>>;
@@ -1622,14 +1661,17 @@ export declare const routeDefinitionSchema: z.ZodObject<{
             publish: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 key: z.ZodString;
                 level: z.ZodOptional<z.ZodEnum<["info", "success", "warning", "error"]>>;
+                message: z.ZodOptional<z.ZodString>;
                 when: z.ZodOptional<z.ZodEnum<["always", "success", "error"]>>;
             }, "strict", z.ZodTypeAny, {
                 key: string;
                 level?: "error" | "info" | "success" | "warning" | undefined;
+                message?: string | undefined;
                 when?: "always" | "error" | "success" | undefined;
             }, {
                 key: string;
                 level?: "error" | "info" | "success" | "warning" | undefined;
+                message?: string | undefined;
                 when?: "always" | "error" | "success" | undefined;
             }>, "many">>;
         }, "strict", z.ZodTypeAny, {
@@ -1637,6 +1679,7 @@ export declare const routeDefinitionSchema: z.ZodObject<{
             publish?: {
                 key: string;
                 level?: "error" | "info" | "success" | "warning" | undefined;
+                message?: string | undefined;
                 when?: "always" | "error" | "success" | undefined;
             }[] | undefined;
         }, {
@@ -1644,6 +1687,7 @@ export declare const routeDefinitionSchema: z.ZodObject<{
             publish?: {
                 key: string;
                 level?: "error" | "info" | "success" | "warning" | undefined;
+                message?: string | undefined;
                 when?: "always" | "error" | "success" | undefined;
             }[] | undefined;
         }>>;
@@ -1659,6 +1703,7 @@ export declare const routeDefinitionSchema: z.ZodObject<{
             publish?: {
                 key: string;
                 level?: "error" | "info" | "success" | "warning" | undefined;
+                message?: string | undefined;
                 when?: "always" | "error" | "success" | undefined;
             }[] | undefined;
         } | undefined;
@@ -1674,6 +1719,7 @@ export declare const routeDefinitionSchema: z.ZodObject<{
             publish?: {
                 key: string;
                 level?: "error" | "info" | "success" | "warning" | undefined;
+                message?: string | undefined;
                 when?: "always" | "error" | "success" | undefined;
             }[] | undefined;
         } | undefined;
@@ -2270,6 +2316,7 @@ export declare const routeDefinitionSchema: z.ZodObject<{
         publish?: {
             key: string;
             level?: "error" | "info" | "success" | "warning" | undefined;
+            message?: string | undefined;
             when?: "always" | "error" | "success" | undefined;
         }[] | undefined;
     } | undefined;
@@ -2285,6 +2332,7 @@ export declare const routeDefinitionSchema: z.ZodObject<{
             publish?: {
                 key: string;
                 level?: "error" | "info" | "success" | "warning" | undefined;
+                message?: string | undefined;
                 when?: "always" | "error" | "success" | undefined;
             }[] | undefined;
         } | undefined;
@@ -2431,6 +2479,7 @@ export declare const routeDefinitionSchema: z.ZodObject<{
         publish?: {
             key: string;
             level?: "error" | "info" | "success" | "warning" | undefined;
+            message?: string | undefined;
             when?: "always" | "error" | "success" | undefined;
         }[] | undefined;
     } | undefined;
@@ -2446,6 +2495,7 @@ export declare const routeDefinitionSchema: z.ZodObject<{
             publish?: {
                 key: string;
                 level?: "error" | "info" | "success" | "warning" | undefined;
+                message?: string | undefined;
                 when?: "always" | "error" | "success" | undefined;
             }[] | undefined;
         } | undefined;
@@ -2604,11 +2654,32 @@ export interface RouteFragmentResponse<TResponse extends z.ZodTypeAny> {
     };
     readonly headers?: Record<string, string>;
 }
+export interface RouteFlashMessage {
+    readonly key?: string;
+    readonly level?: FlashLevel;
+    readonly message: string;
+}
 export interface RouteRedirectResponse {
     readonly status?: RedirectStatus;
     readonly redirect: {
         readonly location: string;
     };
+    /** Messages the next rendered page receives in its `flash`. */
+    readonly flash?: readonly RouteFlashMessage[];
+    readonly headers?: Record<string, string>;
+}
+/** Renders a view in place of the action's response, with the failed form in its loader. */
+export interface RouteRerenderResponse {
+    readonly status?: number;
+    readonly rerender: {
+        readonly view: string;
+        readonly params?: Record<string, string>;
+        readonly form: {
+            readonly id: string;
+            readonly values: FormValues;
+            readonly issues: readonly FormIssue[];
+        };
+    };
     readonly headers?: Record<string, string>;
 }
 export interface RouteErrorResponse {
@@ -2617,8 +2688,8 @@ export interface RouteErrorResponse {
     readonly headers?: Record<string, string>;
 }
 export type RouteNavigationResult<TResponse extends z.ZodTypeAny> = RouteBodyResponse<TResponse> | RouteRedirectResponse | RouteErrorResponse;
-export type RouteMutationResult<TResponse extends z.ZodTypeAny> = RouteBodyResponse<TResponse> | RouteFragmentResponse<TResponse> | RouteRedirectResponse | RouteErrorResponse;
-export type RouteHandlerResult<TResponse extends z.ZodTypeAny> = RouteBodyResponse<TResponse> | RouteFragmentResponse<TResponse> | RouteRedirectResponse | RouteErrorResponse;
+export type RouteMutationResult<TResponse extends z.ZodTypeAny> = RouteBodyResponse<TResponse> | RouteFragmentResponse<TResponse> | RouteRedirectResponse | RouteRerenderResponse | RouteErrorResponse;
+export type RouteHandlerResult<TResponse extends z.ZodTypeAny> = RouteBodyResponse<TResponse> | RouteFragmentResponse<TResponse> | RouteRedirectResponse | RouteRerenderResponse | RouteErrorResponse;
 export type RouteHandler<TContext extends RequestContext, TParams extends z.ZodTypeAny | undefined, TQuery extends z.ZodTypeAny | undefined, TBody extends z.ZodTypeAny | undefined, TResponse extends z.ZodTypeAny> = (context: RouteHandlerContext<TContext, TParams, TQuery, TBody>) => Promise<RouteHandlerResult<TResponse>> | RouteHandlerResult<TResponse>;
 export interface RouteSpec<TContext extends RequestContext = RequestContext, TParams extends z.ZodTypeAny | undefined = undefined, TQuery extends z.ZodTypeAny | undefined = undefined, TBody extends z.ZodTypeAny | undefined = undefined, TResponse extends z.ZodTypeAny = z.ZodTypeAny> {
     readonly definition: RouteDefinition;
@@ -2843,14 +2914,17 @@ export declare const moduleManifestSchema: z.ZodObject<{
             publish: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 key: z.ZodString;
                 level: z.ZodOptional<z.ZodEnum<["info", "success", "warning", "error"]>>;
+                message: z.ZodOptional<z.ZodString>;
                 when: z.ZodOptional<z.ZodEnum<["always", "success", "error"]>>;
             }, "strict", z.ZodTypeAny, {
                 key: string;
                 level?: "error" | "info" | "success" | "warning" | undefined;
+                message?: string | undefined;
                 when?: "always" | "error" | "success" | undefined;
             }, {
                 key: string;
                 level?: "error" | "info" | "success" | "warning" | undefined;
+                message?: string | undefined;
                 when?: "always" | "error" | "success" | undefined;
             }>, "many">>;
         }, "strict", z.ZodTypeAny, {
@@ -2858,6 +2932,7 @@ export declare const moduleManifestSchema: z.ZodObject<{
             publish?: {
                 key: string;
                 level?: "error" | "info" | "success" | "warning" | undefined;
+                message?: string | undefined;
                 when?: "always" | "error" | "success" | undefined;
             }[] | undefined;
         }, {
@@ -2865,6 +2940,7 @@ export declare const moduleManifestSchema: z.ZodObject<{
             publish?: {
                 key: string;
                 level?: "error" | "info" | "success" | "warning" | undefined;
+                message?: string | undefined;
                 when?: "always" | "error" | "success" | undefined;
             }[] | undefined;
         }>>;
@@ -2886,14 +2962,17 @@ export declare const moduleManifestSchema: z.ZodObject<{
                 publish: z.ZodOptional<z.ZodArray<z.ZodObject<{
                     key: z.ZodString;
                     level: z.ZodOptional<z.ZodEnum<["info", "success", "warning", "error"]>>;
+                    message: z.ZodOptional<z.ZodString>;
                     when: z.ZodOptional<z.ZodEnum<["always", "success", "error"]>>;
                 }, "strict", z.ZodTypeAny, {
                     key: string;
                     level?: "error" | "info" | "success" | "warning" | undefined;
+                    message?: string | undefined;
                     when?: "always" | "error" | "success" | undefined;
                 }, {
                     key: string;
                     level?: "error" | "info" | "success" | "warning" | undefined;
+                    message?: string | undefined;
                     when?: "always" | "error" | "success" | undefined;
                 }>, "many">>;
             }, "strict", z.ZodTypeAny, {
@@ -2901,6 +2980,7 @@ export declare const moduleManifestSchema: z.ZodObject<{
                 publish?: {
                     key: string;
                     level?: "error" | "info" | "success" | "warning" | undefined;
+                    message?: string | undefined;
                     when?: "always" | "error" | "success" | undefined;
                 }[] | undefined;
             }, {
@@ -2908,6 +2988,7 @@ export declare const moduleManifestSchema: z.ZodObject<{
                 publish?: {
                     key: string;
                     level?: "error" | "info" | "success" | "warning" | undefined;
+                    message?: string | undefined;
                     when?: "always" | "error" | "success" | undefined;
                 }[] | undefined;
             }>>;
@@ -2923,6 +3004,7 @@ export declare const moduleManifestSchema: z.ZodObject<{
                 publish?: {
                     key: string;
                     level?: "error" | "info" | "success" | "warning" | undefined;
+                    message?: string | undefined;
                     when?: "always" | "error" | "success" | undefined;
                 }[] | undefined;
             } | undefined;
@@ -2938,6 +3020,7 @@ export declare const moduleManifestSchema: z.ZodObject<{
                 publish?: {
                     key: string;
                     level?: "error" | "info" | "success" | "warning" | undefined;
+                    message?: string | undefined;
                     when?: "always" | "error" | "success" | undefined;
                 }[] | undefined;
             } | undefined;
@@ -3534,6 +3617,7 @@ export declare const moduleManifestSchema: z.ZodObject<{
             publish?: {
                 key: string;
                 level?: "error" | "info" | "success" | "warning" | undefined;
+                message?: string | undefined;
                 when?: "always" | "error" | "success" | undefined;
             }[] | undefined;
         } | undefined;
@@ -3549,6 +3633,7 @@ export declare const moduleManifestSchema: z.ZodObject<{
                 publish?: {
                     key: string;
                     level?: "error" | "info" | "success" | "warning" | undefined;
+                    message?: string | undefined;
                     when?: "always" | "error" | "success" | undefined;
                 }[] | undefined;
             } | undefined;
@@ -3695,6 +3780,7 @@ export declare const moduleManifestSchema: z.ZodObject<{
             publish?: {
                 key: string;
                 level?: "error" | "info" | "success" | "warning" | undefined;
+                message?: string | undefined;
                 when?: "always" | "error" | "success" | undefined;
             }[] | undefined;
         } | undefined;
@@ -3710,6 +3796,7 @@ export declare const moduleManifestSchema: z.ZodObject<{
                 publish?: {
                     key: string;
                     level?: "error" | "info" | "success" | "warning" | undefined;
+                    message?: string | undefined;
                     when?: "always" | "error" | "success" | undefined;
                 }[] | undefined;
             } | undefined;
@@ -4019,6 +4106,7 @@ export declare const moduleManifestSchema: z.ZodObject<{
             publish?: {
                 key: string;
                 level?: "error" | "info" | "success" | "warning" | undefined;
+                message?: string | undefined;
                 when?: "always" | "error" | "success" | undefined;
             }[] | undefined;
         } | undefined;
@@ -4034,6 +4122,7 @@ export declare const moduleManifestSchema: z.ZodObject<{
                 publish?: {
                     key: string;
                     level?: "error" | "info" | "success" | "warning" | undefined;
+                    message?: string | undefined;
                     when?: "always" | "error" | "success" | undefined;
                 }[] | undefined;
             } | undefined;
@@ -4239,6 +4328,7 @@ export declare const moduleManifestSchema: z.ZodObject<{
             publish?: {
                 key: string;
                 level?: "error" | "info" | "success" | "warning" | undefined;
+                message?: string | undefined;
                 when?: "always" | "error" | "success" | undefined;
             }[] | undefined;
         } | undefined;
@@ -4254,6 +4344,7 @@ export declare const moduleManifestSchema: z.ZodObject<{
                 publish?: {
                     key: string;
                     level?: "error" | "info" | "success" | "warning" | undefined;
+                    message?: string | undefined;
                     when?: "always" | "error" | "success" | undefined;
                 }[] | undefined;
             } | undefined;
@@ -4459,3 +4550,8 @@ export declare function defineView<TContext extends SSRContext, TParams extends
 export declare function createModule<TRequestContext extends RequestContext, TSSRContext extends SSRContext, TRoutes extends readonly LooseRouteSpec<TRequestContext>[] = readonly LooseRouteSpec<TRequestContext>[], TViews extends readonly LooseViewSpec<TSSRContext>[] = readonly LooseViewSpec<TSSRContext>[]>(definition: ModuleDefinition<TRequestContext, TSSRContext, TRoutes, TViews>): ModuleDefinition<TRequestContext, TSSRContext, TRoutes, TViews>;
 export { fromTsRestRoute, fromTsRestRouter } from './adapters/ts-rest.js';
 export type { FromTsRestRouteOptions, FromTsRestRouterOptions, RouterRouteConfig, } from './adapters/ts-rest.js';
+export { RENDER_PROGRAM_FILE, RENDER_PROGRAM_VERSION, renderFlashMessageSchema, renderFlashSchema, renderNodeSchema, renderPathSchema, renderProgramSchema, renderSourceLocationSchema, } from './render-program.js';
+export type { RenderFlashMessage, RenderNode, RenderPath, RenderProgram, RenderSourceLocation, } from './render-program.js';
+export { executeRenderProgram, programUsesCsrf, readRenderProgram, RENDER_CSRF_FIELD, RenderProgramError, prepareViewData, schemaDeclaresField, } from './render-execute.js';
+export type { ExecuteRenderProgramOptions, PreparedViewData } from './render-execute.js';
+export { CLIENT_NAV_HEADERS, CLIENT_NAV_SUBMISSION_FIELD } from './client-nav.js';

package/dist/index.js

@@ -84,6 +84,7 @@ export const routeFlashMessageSchema = z
     .object({
     key: z.string().min(1),
     level: flashLevelSchema.optional(),
+    message: z.string().min(1).optional(),
     when: flashPublishConditionSchema.optional(),
 })
     .strict();
@@ -231,3 +232,6 @@ export function createModule(definition) {
     return definition;
 }
 export { fromTsRestRoute, fromTsRestRouter } from './adapters/ts-rest.js';
+export { RENDER_PROGRAM_FILE, RENDER_PROGRAM_VERSION, renderFlashMessageSchema, renderFlashSchema, renderNodeSchema, renderPathSchema, renderProgramSchema, renderSourceLocationSchema, } from './render-program.js';
+export { executeRenderProgram, programUsesCsrf, readRenderProgram, RENDER_CSRF_FIELD, RenderProgramError, prepareViewData, schemaDeclaresField, } from './render-execute.js';
+export { CLIENT_NAV_HEADERS, CLIENT_NAV_SUBMISSION_FIELD } from './client-nav.js';

package/dist/render-execute.d.ts

@@ -0,0 +1,36 @@
+import { type RenderProgram, type RenderSourceLocation } from './render-program.js';
+export declare const RENDER_CSRF_FIELD = "_csrf";
+export declare class RenderProgramError extends Error {
+    readonly loc: RenderSourceLocation;
+    constructor(loc: RenderSourceLocation, message: string);
+}
+export interface ExecuteRenderProgramOptions {
+    /**
+     * The session's token for POST forms. `false` renders static output, which has no session:
+     * POST forms render without a token field.
+     */
+    readonly csrfToken?: string | false;
+}
+export declare function readRenderProgram(value: unknown, source: string): RenderProgram;
+export declare function programUsesCsrf(program: RenderProgram): boolean;
+export declare function executeRenderProgram(program: RenderProgram, data: unknown, options?: ExecuteRenderProgramOptions): string;
+export type PreparedViewData = {
+    readonly ok: true;
+    readonly data: unknown;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * Checks a loader's data against its view schema and supplies `flash`, which the framework
+ * owns: the session's messages come first, then any the loader returned. Whether the schema
+ * wants `flash` can depend on the branch a union picks, so the data is parsed with it and,
+ * failing that, without it, starting with what the schema declares.
+ */
+export declare function prepareViewData(schema: unknown, loaded: unknown, flash: readonly unknown[]): PreparedViewData;
+/**
+ * Whether a zod-style schema's underlying object declares `field`, looking through wrappers
+ * such as optional, default, refine and transform, and into unions and intersections. A schema
+ * with no object inside declares nothing.
+ */
+export declare function schemaDeclaresField(schema: unknown, field: string): boolean;

package/dist/render-execute.js

@@ -0,0 +1,269 @@
+import { RENDER_PROGRAM_VERSION, } from './render-program.js';
+export const RENDER_CSRF_FIELD = '_csrf';
+const SAFE_URL_SCHEMES = new Set(['http', 'https', 'mailto', 'tel']);
+const BLOCKED_URL = 'about:invalid';
+// ARIA attributes whose values include the tokens "true" and "false" (WAI-ARIA 1.2). The rest take
+// text or ids, where false still leaves the attribute out.
+const ARIA_TRUE_FALSE = new Set([
+    'aria-atomic',
+    'aria-busy',
+    'aria-checked',
+    'aria-current',
+    'aria-disabled',
+    'aria-expanded',
+    'aria-grabbed',
+    'aria-haspopup',
+    'aria-hidden',
+    'aria-invalid',
+    'aria-modal',
+    'aria-multiline',
+    'aria-multiselectable',
+    'aria-pressed',
+    'aria-readonly',
+    'aria-required',
+    'aria-selected',
+]);
+export class RenderProgramError extends Error {
+    loc;
+    constructor(loc, message) {
+        super(`${loc.file}:${loc.line}: ${message}`);
+        this.name = 'RenderProgramError';
+        this.loc = loc;
+    }
+}
+export function readRenderProgram(value, source) {
+    if (!value ||
+        typeof value !== 'object' ||
+        value.version !== RENDER_PROGRAM_VERSION ||
+        !Array.isArray(value.nodes)) {
+        throw new Error(`Render program ${source} is not a version ${RENDER_PROGRAM_VERSION} program. Rebuild the frontend.`);
+    }
+    return value;
+}
+export function programUsesCsrf(program) {
+    return nodesUseCsrf(program.nodes);
+}
+export function executeRenderProgram(program, data, options = {}) {
+    const out = [];
+    run(program.nodes, data, [], options, out);
+    return out.join('');
+}
+function run(nodes, data, scopes, options, out) {
+    for (const node of nodes) {
+        if (typeof node === 'string') {
+            out.push(node);
+            continue;
+        }
+        switch (node.op) {
+            case 'csrf':
+                if (options.csrfToken === false) {
+                    break;
+                }
+                if (!options.csrfToken) {
+                    throw new Error('A POST form needs a CSRF token, but none was supplied.');
+                }
+                out.push(`<input type="hidden" name="${RENDER_CSRF_FIELD}" value="${escapeAttribute(options.csrfToken)}">`);
+                break;
+            case 'text': {
+                const value = read(node.path, data, scopes);
+                if (value !== null && value !== undefined) {
+                    out.push(escapeText(toText(value, node.loc, `data-text="${node.path.source}"`)));
+                }
+                break;
+            }
+            case 'attr': {
+                const value = read(node.path, data, scopes);
+                // ARIA states are the words "true" and "false", not an attribute's presence.
+                if (typeof value === 'boolean' && ARIA_TRUE_FALSE.has(node.name.toLowerCase())) {
+                    out.push(` ${node.name}="${value}"`);
+                }
+                else if (value === true) {
+                    out.push(` ${node.name}`);
+                }
+                else if (value !== false && value !== null && value !== undefined) {
+                    const label = `data-attr-${node.name}="${node.path.source}"`;
+                    const text = toText(value, node.loc, label);
+                    out.push(` ${node.name}="${escapeAttribute(node.url ? safeAttributeUrl(node.name, text) : text)}"`);
+                }
+                break;
+            }
+            case 'if':
+                if (isTruthy(read(node.path, data, scopes)) !== node.negate) {
+                    run(node.body, data, scopes, options, out);
+                }
+                break;
+            case 'each': {
+                const items = read(node.path, data, scopes);
+                if (items === null || items === undefined) {
+                    break;
+                }
+                if (!Array.isArray(items)) {
+                    throw new RenderProgramError(node.loc, `data-each="${node.path.source} as ${node.as}" needs an array, got ${describe(items)}`);
+                }
+                for (const item of items) {
+                    run(node.body, data, [...scopes, item], options, out);
+                }
+                break;
+            }
+        }
+    }
+}
+function read(path, data, scopes) {
+    let current = path.scope === -1 ? data : scopes[path.scope];
+    for (const key of path.keys) {
+        if (current === null || typeof current !== 'object' || !Object.hasOwn(current, key)) {
+            return undefined;
+        }
+        current = current[key];
+    }
+    return current;
+}
+function isTruthy(value) {
+    if (Array.isArray(value)) {
+        return value.length > 0;
+    }
+    return Boolean(value);
+}
+function toText(value, loc, label) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (typeof value === 'number' || typeof value === 'bigint') {
+        return String(value);
+    }
+    throw new RenderProgramError(loc, `${label} needs a string or number, got ${describe(value)}`);
+}
+/** Every URL in the value is checked: `srcset` lists candidates, `ping` lists URLs. */
+function safeAttributeUrl(name, value) {
+    if (name === 'srcset' || name === 'imagesrcset') {
+        return value
+            .split(',')
+            .map((candidate) => {
+            const [url = '', ...descriptors] = candidate.trim().split(/\s+/);
+            return [safeUrl(url), ...descriptors].join(' ');
+        })
+            .join(', ');
+    }
+    if (name === 'ping') {
+        return value.split(/\s+/).filter(Boolean).map(safeUrl).join(' ');
+    }
+    return safeUrl(value);
+}
+/**
+ * Checks a loader's data against its view schema and supplies `flash`, which the framework
+ * owns: the session's messages come first, then any the loader returned. Whether the schema
+ * wants `flash` can depend on the branch a union picks, so the data is parsed with it and,
+ * failing that, without it, starting with what the schema declares.
+ */
+export function prepareViewData(schema, loaded, flash) {
+    const withFlash = mergeFlash(loaded, flash);
+    if (!schema || typeof schema.safeParse !== 'function') {
+        return { ok: true, data: withFlash };
+    }
+    const attempts = schemaDeclaresField(schema, 'flash') ? [withFlash, loaded] : [loaded, withFlash];
+    let firstError;
+    for (const [index, input] of attempts.entries()) {
+        const parsed = schema.safeParse(input);
+        if (parsed.success) {
+            return { ok: true, data: ensureFlash(parsed.data, flash) };
+        }
+        if (index === 0) {
+            firstError = parsed.error;
+        }
+    }
+    return { ok: false, error: describeSchemaError(firstError) };
+}
+function mergeFlash(value, flash) {
+    if (!isPlainObject(value)) {
+        return value;
+    }
+    const own = value.flash;
+    if (own !== undefined && !Array.isArray(own)) {
+        return value;
+    }
+    return { ...value, flash: [...flash, ...(own ?? [])] };
+}
+function ensureFlash(value, flash) {
+    return isPlainObject(value) && !('flash' in value) ? { ...value, flash: [...flash] } : value;
+}
+function isPlainObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function describeSchemaError(error) {
+    const issues = error
+        ?.issues;
+    if (!Array.isArray(issues) || issues.length === 0) {
+        return error instanceof Error ? error.message : String(error);
+    }
+    return issues
+        .map((issue) => `${(issue.path ?? []).join('.') || '(root)'}: ${issue.message ?? 'invalid'}`)
+        .join('; ');
+}
+/**
+ * Whether a zod-style schema's underlying object declares `field`, looking through wrappers
+ * such as optional, default, refine and transform, and into unions and intersections. A schema
+ * with no object inside declares nothing.
+ */
+export function schemaDeclaresField(schema, field) {
+    return declares(schema, field, new Set());
+}
+function declares(schema, field, seen) {
+    if (!schema || typeof schema !== 'object' || seen.has(schema)) {
+        return false;
+    }
+    seen.add(schema);
+    const shape = schema.shape;
+    if (shape && typeof shape === 'object') {
+        return field in shape;
+    }
+    const def = schema._def;
+    if (!def) {
+        return false;
+    }
+    const inner = [def.innerType, def.schema, def.in, def.type, def.left, def.right];
+    if (typeof def.getter === 'function') {
+        inner.push(def.getter());
+    }
+    if (Array.isArray(def.options)) {
+        inner.push(...def.options);
+    }
+    return inner.some((candidate) => declares(candidate, field, seen));
+}
+function safeUrl(value) {
+    const normalized = Array.from(value)
+        .filter((character) => {
+        const code = character.charCodeAt(0);
+        return code > 0x20 && code !== 0x7f;
+    })
+        .join('')
+        .toLowerCase();
+    const scheme = /^([a-z][a-z0-9+.-]*):/.exec(normalized);
+    if (scheme && !SAFE_URL_SCHEMES.has(scheme[1])) {
+        return BLOCKED_URL;
+    }
+    return value;
+}
+function nodesUseCsrf(nodes) {
+    return nodes.some((node) => typeof node !== 'string' &&
+        (node.op === 'csrf' || ((node.op === 'if' || node.op === 'each') && nodesUseCsrf(node.body))));
+}
+function describe(value) {
+    if (Array.isArray(value)) {
+        return 'an array';
+    }
+    if (value === null) {
+        return 'null';
+    }
+    return typeof value === 'object' ? 'an object' : `a ${typeof value}`;
+}
+function escapeText(value) {
+    return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+}
+function escapeAttribute(value) {
+    return value
+        .replaceAll('&', '&amp;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&#39;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;');
+}

package/dist/render-program.d.ts

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+export declare const RENDER_PROGRAM_VERSION = 1;
+export declare const RENDER_PROGRAM_FILE = "index.program.json";
+export declare const renderSourceLocationSchema: z.ZodObject<{
+    file: z.ZodString;
+    line: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    file: string;
+    line: number;
+}, {
+    file: string;
+    line: number;
+}>;
+export type RenderSourceLocation = z.infer<typeof renderSourceLocationSchema>;
+export declare const renderPathSchema: z.ZodObject<{
+    source: z.ZodString;
+    scope: z.ZodNumber;
+    keys: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    source: string;
+    scope: number;
+    keys: string[];
+}, {
+    source: string;
+    scope: number;
+    keys: string[];
+}>;
+export type RenderPath = z.infer<typeof renderPathSchema>;
+export type RenderNode = string | {
+    readonly op: 'text';
+    readonly path: RenderPath;
+    readonly loc: RenderSourceLocation;
+} | {
+    readonly op: 'attr';
+    readonly name: string;
+    readonly url: boolean;
+    readonly path: RenderPath;
+    readonly loc: RenderSourceLocation;
+} | {
+    readonly op: 'if';
+    readonly negate: boolean;
+    readonly path: RenderPath;
+    readonly loc: RenderSourceLocation;
+    readonly body: readonly RenderNode[];
+} | {
+    readonly op: 'each';
+    readonly as: string;
+    readonly path: RenderPath;
+    readonly loc: RenderSourceLocation;
+    readonly body: readonly RenderNode[];
+} | {
+    readonly op: 'csrf';
+};
+export declare const renderNodeSchema: z.ZodType<RenderNode>;
+export declare const renderProgramSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    page: z.ZodString;
+    source: z.ZodString;
+    bindings: z.ZodNumber;
+    nodes: z.ZodArray<z.ZodType<RenderNode, z.ZodTypeDef, RenderNode>, "many">;
+}, "strip", z.ZodTypeAny, {
+    version: 1;
+    page: string;
+    source: string;
+    bindings: number;
+    nodes: RenderNode[];
+}, {
+    version: 1;
+    page: string;
+    source: string;
+    bindings: number;
+    nodes: RenderNode[];
+}>;
+export type RenderProgram = z.infer<typeof renderProgramSchema>;
+export declare const renderFlashMessageSchema: z.ZodObject<{
+    level: z.ZodEnum<["info", "success", "warning", "error"]>;
+    message: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    level: "error" | "info" | "success" | "warning";
+    message: string;
+}, {
+    level: "error" | "info" | "success" | "warning";
+    message: string;
+}>;
+export type RenderFlashMessage = z.infer<typeof renderFlashMessageSchema>;
+export declare const renderFlashSchema: z.ZodArray<z.ZodObject<{
+    level: z.ZodEnum<["info", "success", "warning", "error"]>;
+    message: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    level: "error" | "info" | "success" | "warning";
+    message: string;
+}, {
+    level: "error" | "info" | "success" | "warning";
+    message: string;
+}>, "many">;

package/dist/render-program.js

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+export const RENDER_PROGRAM_VERSION = 1;
+export const RENDER_PROGRAM_FILE = 'index.program.json';
+export const renderSourceLocationSchema = z.object({
+    file: z.string().min(1),
+    line: z.number().int().positive(),
+});
+export const renderPathSchema = z.object({
+    source: z.string().min(1),
+    scope: z.number().int().min(-1),
+    keys: z.array(z.string().min(1)),
+});
+export const renderNodeSchema = z.lazy(() => z.union([
+    z.string(),
+    z.object({ op: z.literal('text'), path: renderPathSchema, loc: renderSourceLocationSchema }),
+    z.object({
+        op: z.literal('attr'),
+        name: z.string().min(1),
+        url: z.boolean(),
+        path: renderPathSchema,
+        loc: renderSourceLocationSchema,
+    }),
+    z.object({
+        op: z.literal('if'),
+        negate: z.boolean(),
+        path: renderPathSchema,
+        loc: renderSourceLocationSchema,
+        body: z.array(renderNodeSchema),
+    }),
+    z.object({
+        op: z.literal('each'),
+        as: z.string().min(1),
+        path: renderPathSchema,
+        loc: renderSourceLocationSchema,
+        body: z.array(renderNodeSchema),
+    }),
+    z.object({ op: z.literal('csrf') }),
+]));
+export const renderProgramSchema = z.object({
+    version: z.literal(RENDER_PROGRAM_VERSION),
+    page: z.string().min(1),
+    source: z.string().min(1),
+    bindings: z.number().int().min(0),
+    nodes: z.array(renderNodeSchema),
+});
+export const renderFlashMessageSchema = z.object({
+    level: z.enum(['info', 'success', 'warning', 'error']),
+    message: z.string(),
+});
+export const renderFlashSchema = z.array(renderFlashMessageSchema);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webstir-io/module-contract",
-  "version": "0.1.69",
+  "version": "0.3.0",
   "description": "Public contract definitions for Webstir frontend and backend module providers.",
   "type": "module",
   "main": "dist/index.js",
@@ -11,6 +11,11 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./client-nav": {
+      "types": "./dist/client-nav.d.ts",
+      "import": "./dist/client-nav.js",
+      "default": "./dist/client-nav.js"
+    },
     "./ts-rest": {
       "types": "./dist/adapters/ts-rest.d.ts",
       "import": "./dist/adapters/ts-rest.js",

package/schema/module-manifest.schema.json

@@ -174,6 +174,10 @@
                             "error"
                           ]
                         },
+                        "message": {
+                          "type": "string",
+                          "minLength": 1
+                        },
                         "when": {
                           "type": "string",
                           "enum": [

package/schema/route-definition.schema.json

@@ -103,6 +103,10 @@
                       "error"
                     ]
                   },
+                  "message": {
+                    "type": "string",
+                    "minLength": 1
+                  },
                   "when": {
                     "type": "string",
                     "enum": [