@kuratchi/js 0.0.18 → 0.0.20

package/dist/compiler/template.js

@@ -152,20 +152,24 @@ function buildAppendStatement(expression, emitCall) {
     // Otherwise, use array push for O(n) performance
     return emitCall ? `${emitCall}(${expression});` : `__parts.push(${expression});`;
 }
-function extractPollFragmentExpr(tagText, rpcNameMap) {
-    const pollMatch = tagText.match(/\bdata-poll=\{([\s\S]*?)\}/);
-    if (!pollMatch)
-        return null;
-    const inner = pollMatch[1].trim();
+function buildPollFragmentExpr(inner, rpcNameMap, pollIndex = 0) {
     const callMatch = inner.match(/^([A-Za-z_$][\w$]*)\(([\s\S]*)\)$/);
     if (!callMatch)
         return null;
     const fnName = callMatch[1];
     const rpcName = rpcNameMap?.get(fnName) || fnName;
     const argsExpr = (callMatch[2] || '').trim();
+    const fragmentPrefix = `__poll_${pollIndex}`;
     if (!argsExpr)
-        return JSON.stringify(`__poll_${rpcName}`);
-    return `'__poll_' + String(${argsExpr}).replace(/[^a-zA-Z0-9]/g, '_')`;
+        return JSON.stringify(`${fragmentPrefix}_${rpcName}`);
+    return `${JSON.stringify(fragmentPrefix + '_')} + String(${argsExpr}).replace(/[^a-zA-Z0-9]/g, '_')`;
+}
+function extractPollFragmentExpr(tagText, rpcNameMap, pollIndex = 0) {
+    const pollMatch = tagText.match(/\bdata-poll=\{([\s\S]*?)\}/);
+    if (!pollMatch)
+        return null;
+    const inner = pollMatch[1].trim();
+    return buildPollFragmentExpr(inner, rpcNameMap, pollIndex);
 }
 function findTagEnd(template, start) {
     let quote = null;
@@ -208,6 +212,7 @@ function instrumentPollFragments(template, rpcNameMap) {
     const out = [];
     const stack = [];
     let cursor = 0;
+    let pollIndex = 0;
     while (cursor < template.length) {
         const lt = template.indexOf('<', cursor);
         if (lt === -1) {
@@ -245,15 +250,20 @@ function instrumentPollFragments(template, rpcNameMap) {
             continue;
         }
         const openMatch = tagText.match(/^<\s*([A-Za-z][\w:-]*)\b/);
-        out.push(tagText);
         if (!openMatch) {
+            out.push(tagText);
             cursor = tagEnd + 1;
             continue;
         }
         const tagName = openMatch[1].toLowerCase();
         const isVoidLike = /\/\s*>$/.test(tagText) || /^(area|base|br|col|embed|hr|img|input|link|meta|param|source|track|wbr)$/i.test(tagName);
-        const fragmentExpr = extractPollFragmentExpr(tagText, rpcNameMap);
+        const fragmentExpr = extractPollFragmentExpr(tagText, rpcNameMap, pollIndex);
+        const instrumentedTagText = fragmentExpr
+            ? tagText.replace(/\bdata-poll=\{([\s\S]*?)\}/, (match) => `${match} data-kuratchi-poll-fragment={${fragmentExpr}}`)
+            : tagText;
+        out.push(instrumentedTagText);
         if (fragmentExpr) {
+            pollIndex += 1;
             out.push(`${FRAGMENT_OPEN_MARKER}${encodeURIComponent(fragmentExpr)}-->`);
             if (isVoidLike) {
                 out.push(FRAGMENT_CLOSE_MARKER);
@@ -404,6 +414,7 @@ export function compileTemplate(template, componentNames, actionNames, rpcNameMa
                 const childTemplate = childLines.join('\n');
                 const childBody = compileTemplate(childTemplate, componentNames, actionNames, rpcNameMap, {
                     clientRouteRegistry: options.clientRouteRegistry,
+                    awaitQueryBindings: options.awaitQueryBindings,
                 });
                 // Wrap in an IIFE that returns the children HTML
                 const childrenExpr = `(function() { ${childBody}; return __html; })()`;
@@ -604,6 +615,14 @@ function transformClientScriptBlock(block) {
     // TypeScript is preserved — wrangler's esbuild handles transpilation
     return `${openTag}${out.join('\n')}${closeTag}`;
 }
+function extractAwaitTemplateCall(expr) {
+    const match = expr.trim().match(/^await\s+([A-Za-z_$][\w$]*)\(([\s\S]*)\)$/);
+    if (!match)
+        return null;
+    const fnName = match[1];
+    const argsExpr = (match[2] || '').trim();
+    return { fnName, argsExpr, awaitExpr: `${fnName}(${argsExpr})` };
+}
 function braceDelta(line) {
     let delta = 0;
     let inSingle = false;
@@ -843,6 +862,7 @@ function tryCompileComponentTag(line, componentNames, actionNames, rpcNameMap, o
         // Compile the inline content as a mini-template to handle {expr} interpolation
         const childBody = compileTemplate(innerContent, componentNames, actionNames, rpcNameMap, {
             clientRouteRegistry: options.clientRouteRegistry,
+            awaitQueryBindings: options.awaitQueryBindings,
         });
         const childrenExpr = `(function() { ${childBody}; return __html; })()`;
         return buildAppendStatement(`${funcName}({ ${propsStr}${propsStr ? ', ' : ''}children: ${childrenExpr} }, __esc)`, options.emitCall);
@@ -1028,8 +1048,14 @@ function compileHtmlSegment(line, actionNames, rpcNameMap, options = {}) {
                     pos = closeIdx + 1;
                     continue;
                 }
+                else if (attrName === 'data-kuratchi-poll-fragment') {
+                    result = result.replace(/\s*data-kuratchi-poll-fragment=$/, '');
+                    result += ` data-poll-id="\${__signFragment(${inner})}"`;
+                    pos = closeIdx + 1;
+                    continue;
+                }
                 else if (attrName === 'data-poll') {
-                    // data-poll={fn(args)} → data-poll="fnName" data-poll-args="[serialized]" data-poll-id="signed-id"
+                    // data-poll={fn(args)} → data-poll="fnName" data-poll-args="[serialized]"
                     const pollCallMatch = inner.match(/^(\w+)\((.*)\)$/);
                     if (pollCallMatch) {
                         const fnName = pollCallMatch[1];
@@ -1037,16 +1063,11 @@ function compileHtmlSegment(line, actionNames, rpcNameMap, options = {}) {
                         const argsExpr = pollCallMatch[2].trim();
                         // Remove the trailing "data-poll=" we already appended
                         result = result.replace(/\s*data-poll=$/, '');
-                        // Emit data-poll, data-poll-args, and signed data-poll-id (signed at runtime for security)
+                        // Emit data-poll and data-poll-args. The signed poll fragment ID is emitted
+                        // from the synthetic data-kuratchi-poll-fragment attribute injected earlier.
                         result += ` data-poll="${rpcName}"`;
                         if (argsExpr) {
                             result += ` data-poll-args="\${__esc(JSON.stringify([${argsExpr}]))}"`;
-                            // Sign the fragment ID at runtime with __signFragment(fragmentId, routePath)
-                            result += ` data-poll-id="\${__signFragment('__poll_' + String(${argsExpr}).replace(/[^a-zA-Z0-9]/g, '_'))}"`;
-                        }
-                        else {
-                            // No args - sign with function name as base ID
-                            result += ` data-poll-id="\${__signFragment('__poll_${rpcName}')}"`;
                         }
                     }
                     pos = closeIdx + 1;
@@ -1119,7 +1140,18 @@ function compileHtmlSegment(line, actionNames, rpcNameMap, options = {}) {
                 }
             }
             else {
-                result += `\${__esc(${inner})}`;
+                const awaitCall = extractAwaitTemplateCall(inner);
+                const awaitBinding = awaitCall ? options.awaitQueryBindings?.get(awaitCall.awaitExpr) : null;
+                if (awaitCall && awaitBinding) {
+                    result += `<span data-remote-read="${awaitBinding.rpcId}" data-get="${awaitBinding.rpcId}"`;
+                    if (awaitCall.argsExpr) {
+                        result += ` data-get-args="\${__esc(JSON.stringify([${awaitCall.argsExpr}]))}"`;
+                    }
+                    result += `>\${__esc(((${awaitBinding.asName} && ${awaitBinding.asName}.data) ?? ''))}</span>`;
+                }
+                else {
+                    result += `\${__esc(${inner})}`;
+                }
             }
         }
         pos = closeIdx + 1;

package/dist/compiler/worker-output-pipeline.js

@@ -19,7 +19,9 @@ export function toWorkerImportPath(projectDir, outDir, filePath) {
     return rel.replace(/\.(ts|js|mjs|cjs)$/, '');
 }
 export function buildWorkerEntrypointSource(opts) {
+    const doClassSet = new Set(opts.doClassNames);
     const workerClassExports = opts.workerClassEntries
+        .filter((entry) => !doClassSet.has(entry.className))
         .map((entry) => {
         const importPath = toWorkerImportPath(opts.projectDir, opts.outDir, entry.file);
         if (entry.exportKind === 'default') {

package/dist/compiler/wrangler-sync.d.ts

@@ -6,6 +6,9 @@ export interface WranglerSyncConfig {
     workflows: WranglerSyncEntry[];
     containers: WranglerSyncEntry[];
     durableObjects: WranglerSyncEntry[];
+    /** Relative path to the public assets directory (e.g. '.kuratchi/public/'). When set, the
+     * `assets.directory` and `assets.binding` keys in wrangler.jsonc are kept in sync automatically. */
+    assetsDirectory?: string;
 }
 export declare function syncWranglerConfig(opts: {
     projectDir: string;

package/dist/compiler/wrangler-sync.js

@@ -128,24 +128,23 @@ export function syncWranglerConfig(opts) {
     }
     if (opts.config.containers.length > 0) {
         const existingContainers = wranglerConfig.containers || [];
-        const existingByBinding = new Map(existingContainers.map((container) => [container.binding, container]));
+        const existingByClassName = new Map(existingContainers.map((container) => [container.class_name, container]));
         for (const container of opts.config.containers) {
             const name = container.binding.toLowerCase().replace(/_/g, '-');
             const entry = {
                 name,
-                binding: container.binding,
                 class_name: container.className,
             };
-            const existing = existingByBinding.get(container.binding);
+            const existing = existingByClassName.get(container.className);
             if (!existing) {
                 existingContainers.push(entry);
                 changed = true;
-                console.log(`[kuratchi] Added container "${container.binding}" to wrangler config`);
+                console.log(`[kuratchi] Added container "${container.className}" to wrangler config`);
             }
-            else if (existing.class_name !== container.className) {
-                existing.class_name = container.className;
+            else if (existing.name !== name) {
+                existing.name = name;
                 changed = true;
-                console.log(`[kuratchi] Updated container "${container.binding}" class_name to "${container.className}"`);
+                console.log(`[kuratchi] Updated container "${container.className}" name to "${name}"`);
             }
         }
         wranglerConfig.containers = existingContainers;
@@ -170,13 +169,28 @@ export function syncWranglerConfig(opts) {
                 changed = true;
                 console.log(`[kuratchi] Added durable_object "${durableObject.binding}" to wrangler config`);
             }
-            else if (existing.class_name !== durableObject.className) {
-                existing.class_name = durableObject.className;
+        }
+        wranglerConfig.durable_objects.bindings = existingBindings;
+    }
+    if (opts.config.assetsDirectory !== undefined) {
+        const existing = wranglerConfig.assets;
+        if (!existing) {
+            wranglerConfig.assets = { directory: opts.config.assetsDirectory, binding: 'ASSETS' };
+            changed = true;
+            console.log(`[kuratchi] Added static assets directory "${opts.config.assetsDirectory}" to wrangler config`);
+        }
+        else {
+            if (existing.directory !== opts.config.assetsDirectory) {
+                existing.directory = opts.config.assetsDirectory;
+                changed = true;
+                console.log(`[kuratchi] Updated static assets directory to "${opts.config.assetsDirectory}" in wrangler config`);
+            }
+            if (!existing.binding) {
+                existing.binding = 'ASSETS';
                 changed = true;
-                console.log(`[kuratchi] Updated durable_object "${durableObject.binding}" class_name to "${durableObject.className}"`);
+                console.log(`[kuratchi] Added ASSETS binding to static assets config in wrangler config`);
             }
         }
-        wranglerConfig.durable_objects.bindings = existingBindings;
     }
     if (!changed)
         return;

package/dist/create.js

@@ -211,25 +211,25 @@ function scaffold(dir, opts) {
     write(dir, 'tsconfig.json', genTsConfig());
     write(dir, '.gitignore', genGitIgnore());
     write(dir, 'src/routes/layout.html', genLayout(opts));
-    write(dir, 'src/routes/page.html', genLandingPage(opts));
+    write(dir, 'src/routes/index.html', genLandingPage(opts));
     if (orm) {
         write(dir, 'src/schemas/app.ts', genSchema(opts));
         write(dir, 'src/database/items.ts', genItemsCrud());
-        write(dir, 'src/routes/items/page.html', genItemsPage());
+        write(dir, 'src/routes/items/index.html', genItemsPage());
     }
     if (enableDO) {
         write(dir, 'src/schemas/notes.ts', genNotesSchema());
         write(dir, 'src/server/notes.do.ts', genNotesDoHandler());
         write(dir, 'src/database/notes.ts', genNotesDb());
-        write(dir, 'src/routes/notes/page.html', genNotesPage());
+        write(dir, 'src/routes/notes/index.html', genNotesPage());
     }
     if (auth) {
         write(dir, '.dev.vars', genDevVars());
         write(dir, 'src/database/auth.ts', genAuthFunctions());
         write(dir, 'src/database/admin.ts', genAdminLoader());
-        write(dir, 'src/routes/auth/login/page.html', genLoginPage());
-        write(dir, 'src/routes/auth/signup/page.html', genSignupPage());
-        write(dir, 'src/routes/admin/page.html', genAdminPage());
+        write(dir, 'src/routes/auth/login/index.html', genLoginPage());
+        write(dir, 'src/routes/auth/signup/index.html', genSignupPage());
+        write(dir, 'src/routes/admin/index.html', genAdminPage());
     }
 }
 function write(dir, filePath, content) {

package/dist/index.d.ts

@@ -8,9 +8,11 @@ export { defineConfig } from './runtime/config.js';
 export { defineRuntime } from './runtime/runtime.js';
 export { getCtx, getEnv, getRequest, getLocals, getParams, getParam, RedirectError, redirect, goto, setBreadcrumbs, getBreadcrumbs, breadcrumbsHome, breadcrumbsPrev, breadcrumbsNext, breadcrumbsCurrent, buildDefaultBreadcrumbs, } from './runtime/context.js';
 export { kuratchiDO, doRpc, getDb } from './runtime/do.js';
+export { SchemaValidationError, schema, } from './runtime/schema.js';
 export { ActionError } from './runtime/action.js';
 export { PageError } from './runtime/page-error.js';
 export { extractSubdomainSlug, extractSlugFromPrefix, matchContainerViewPath, rewriteProxyLocationHeader, buildContainerRequest, createContainerEnvVars, startContainer, proxyToContainer, handleContainerRouting, forwardJsonPostToContainerDO, matchSiteViewPath, buildSiteContainerRequest, createWpContainerEnvVars, startSiteContainer, proxyToSiteContainer, } from './runtime/containers.js';
 export type { AppConfig, kuratchiConfig, DatabaseConfig, AuthConfig, RouteContext, RouteModule, RuntimeContext, RuntimeDefinition, RuntimeStep, RuntimeNext, RuntimeErrorResult, } from './runtime/types.js';
 export type { RpcOf } from './runtime/do.js';
+export type { SchemaType, InferSchema } from './runtime/schema.js';
 export { url, pathname, searchParams, headers, method, params, slug } from './runtime/request.js';

package/dist/index.js

@@ -9,6 +9,7 @@ export { defineConfig } from './runtime/config.js';
 export { defineRuntime } from './runtime/runtime.js';
 export { getCtx, getEnv, getRequest, getLocals, getParams, getParam, RedirectError, redirect, goto, setBreadcrumbs, getBreadcrumbs, breadcrumbsHome, breadcrumbsPrev, breadcrumbsNext, breadcrumbsCurrent, buildDefaultBreadcrumbs, } from './runtime/context.js';
 export { kuratchiDO, doRpc, getDb } from './runtime/do.js';
+export { SchemaValidationError, schema, } from './runtime/schema.js';
 export { ActionError } from './runtime/action.js';
 export { PageError } from './runtime/page-error.js';
 export { extractSubdomainSlug, extractSlugFromPrefix, matchContainerViewPath, rewriteProxyLocationHeader, buildContainerRequest, createContainerEnvVars, startContainer, proxyToContainer, handleContainerRouting, forwardJsonPostToContainerDO, 

package/dist/runtime/context.d.ts

@@ -20,6 +20,12 @@ export declare class RedirectError extends Error {
 }
 /** Called by the framework at the start of each request */
 export declare function __setRequestContext(ctx: any, request: Request, env?: Record<string, any>): void;
+/**
+ * Push a new request context for the duration of a DO RPC call.
+ * Saves current state and returns a restore function.
+ * @internal
+ */
+export declare function __pushRequestContext(rpcContext: any, ctx: any, env: any): () => void;
 /** Get the execution context (Worker: ExecutionContext, DO: DurableObjectState) */
 export declare function getCtx(): any;
 /** Get the current environment bindings */

package/dist/runtime/context.js

@@ -32,12 +32,33 @@ export function __setRequestContext(ctx, request, env) {
     __locals = {};
     __setRequestState(request);
     // Expose context on globalThis for @kuratchi/auth and other packages
-    // Workers are single-threaded per request — this is safe
+    // Workers are single-threaded per request — this is safe
     globalThis.__kuratchi_context__ = {
         get request() { return __request; },
         get locals() { return __locals; },
     };
 }
+/**
+ * Push a new request context for the duration of a DO RPC call.
+ * Saves current state and returns a restore function.
+ * @internal
+ */
+export function __pushRequestContext(rpcContext, ctx, env) {
+    const prevCtx = __ctx;
+    const prevRequest = __request;
+    const prevEnv = __env;
+    const prevLocals = __locals;
+    __ctx = ctx;
+    __request = rpcContext?.request ?? __request;
+    __env = env ?? __env;
+    __locals = rpcContext?.locals ? { ...rpcContext.locals } : {};
+    return () => {
+        __ctx = prevCtx;
+        __request = prevRequest;
+        __env = prevEnv;
+        __locals = prevLocals;
+    };
+}
 /** Get the execution context (Worker: ExecutionContext, DO: DurableObjectState) */
 export function getCtx() {
     const doSelf = __getDoSelf();

package/dist/runtime/generated-worker.d.ts

@@ -14,6 +14,7 @@ export interface GeneratedPageRoute {
     load?: (params: Record<string, string>) => Promise<unknown> | unknown;
     actions?: Record<string, (...args: any[]) => Promise<unknown> | unknown>;
     rpc?: Record<string, (...args: any[]) => Promise<unknown> | unknown>;
+    rpcSchemas?: Record<string, any>;
     /** Allowed query function names for this route (for query override validation) */
     allowedQueries?: string[];
     render: (data: Record<string, any>) => PageRenderOutput;

package/dist/runtime/generated-worker.js

@@ -1,6 +1,7 @@
 import { __esc, __getLocals, __setLocal, __setRequestContext, buildDefaultBreadcrumbs } from './context.js';
 import { Router } from './router.js';
 import { initCsrf, getCsrfCookieHeader, validateRpcRequest, validateActionRequest, validateSignedFragment, validateQueryOverride, parseQueryArgs, CSRF_DEFAULTS, } from './security.js';
+import { SchemaValidationError, parseRpcArgsPayload, validateSchemaInput, } from './schema.js';
 export function createGeneratedWorker(opts) {
     const router = new Router();
     const runtimeEntries = __getRuntimeEntries(opts.runtimeDefinition);
@@ -225,19 +226,22 @@ async function __handleRpc(route, workflowStatusRpc, runtimeCtx, securityConfig)
         }));
     }
     try {
-        const rpcArgsStr = url.searchParams.get('_args');
-        let rpcArgs = [];
-        if (rpcArgsStr) {
-            const parsed = JSON.parse(rpcArgsStr);
-            rpcArgs = Array.isArray(parsed) ? parsed : [];
-        }
+        const rpcArgs = parseRpcArgsPayload(url.searchParams.get('_args'));
         const rpcFn = hasRouteRpc ? route.rpc[rpcName] : workflowStatusRpc[rpcName];
-        const rpcResult = await rpcFn(...rpcArgs);
+        const rpcSchema = hasRouteRpc ? route.rpcSchemas?.[rpcName] : undefined;
+        const validatedArgs = hasRouteRpc ? validateSchemaInput(rpcSchema, rpcArgs) : rpcArgs;
+        const rpcResult = await rpcFn(...validatedArgs);
         return __attachCookies(new Response(JSON.stringify({ ok: true, data: rpcResult }), {
             headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },
         }));
     }
     catch (err) {
+        if (err instanceof SchemaValidationError || err?.isSchemaValidationError) {
+            return __secHeaders(new Response(JSON.stringify({ ok: false, error: err.message }), {
+                status: 400,
+                headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },
+            }));
+        }
         console.error('[kuratchi] RPC error:', err);
         const errMsg = __sanitizeErrorMessage(err);
         return __secHeaders(new Response(JSON.stringify({ ok: false, error: errMsg }), {

package/dist/runtime/index.d.ts

@@ -5,6 +5,8 @@ export { defineRuntime } from './runtime.js';
 export { Router, filePathToPattern } from './router.js';
 export { getCtx, getRequest, getLocals, getParams, getParam, RedirectError, redirect, goto, setBreadcrumbs, getBreadcrumbs, breadcrumbsHome, breadcrumbsPrev, breadcrumbsNext, breadcrumbsCurrent, buildDefaultBreadcrumbs, } from './context.js';
 export { kuratchiDO, doRpc } from './do.js';
+export { SchemaValidationError, schema, validateSchemaInput, parseRpcArgsPayload, } from './schema.js';
+export type { SchemaType, InferSchema, } from './schema.js';
 export { initCsrf, getCsrfToken, validateCsrf, getCsrfCookieHeader, validateRpcRequest, validateActionRequest, applySecurityHeaders, signFragmentId, validateSignedFragment, validateQueryOverride, parseQueryArgs, CSRF_DEFAULTS, } from './security.js';
 export type { RpcSecurityConfig, ActionSecurityConfig, SecurityHeadersConfig, } from './security.js';
 export { extractSubdomainSlug, extractSlugFromPrefix, matchContainerViewPath, rewriteProxyLocationHeader, buildContainerRequest, createContainerEnvVars, startContainer, proxyToContainer, handleContainerRouting, forwardJsonPostToContainerDO, matchSiteViewPath, buildSiteContainerRequest, createWpContainerEnvVars, startSiteContainer, proxyToSiteContainer, } from './containers.js';

package/dist/runtime/index.js

@@ -5,6 +5,7 @@ export { defineRuntime } from './runtime.js';
 export { Router, filePathToPattern } from './router.js';
 export { getCtx, getRequest, getLocals, getParams, getParam, RedirectError, redirect, goto, setBreadcrumbs, getBreadcrumbs, breadcrumbsHome, breadcrumbsPrev, breadcrumbsNext, breadcrumbsCurrent, buildDefaultBreadcrumbs, } from './context.js';
 export { kuratchiDO, doRpc } from './do.js';
+export { SchemaValidationError, schema, validateSchemaInput, parseRpcArgsPayload, } from './schema.js';
 export { initCsrf, getCsrfToken, validateCsrf, getCsrfCookieHeader, validateRpcRequest, validateActionRequest, applySecurityHeaders, signFragmentId, validateSignedFragment, validateQueryOverride, parseQueryArgs, CSRF_DEFAULTS, } from './security.js';
 export { extractSubdomainSlug, extractSlugFromPrefix, matchContainerViewPath, rewriteProxyLocationHeader, buildContainerRequest, createContainerEnvVars, startContainer, proxyToContainer, handleContainerRouting, forwardJsonPostToContainerDO, 
 // Compatibility aliases

package/dist/runtime/schema.d.ts

@@ -0,0 +1,49 @@
+export declare class SchemaValidationError extends Error {
+    readonly isSchemaValidationError = true;
+    readonly status = 400;
+    constructor(message: string);
+}
+export interface SchemaType<T> {
+    parse(input: unknown, path?: string): T;
+}
+export type InferSchema<T extends SchemaType<any>> = T extends SchemaType<infer U> ? U : never;
+declare class BaseSchema<T> implements SchemaType<T> {
+    protected readonly parser: (input: unknown, path: string) => T;
+    constructor(parser: (input: unknown, path: string) => T);
+    parse(input: unknown, path?: string): T;
+    optional(defaultValue?: T): SchemaType<T | undefined>;
+    list(): SchemaType<T[]>;
+}
+declare class StringSchema extends BaseSchema<string> {
+    constructor();
+    min(length: number): SchemaType<string>;
+}
+declare class NumberSchema extends BaseSchema<number> {
+    constructor();
+    min(value: number): SchemaType<number>;
+}
+declare class BooleanSchema extends BaseSchema<boolean> {
+    constructor();
+}
+declare class FileSchema extends BaseSchema<File> {
+    constructor();
+}
+type ShapeRecord = Record<string, SchemaType<any>>;
+type InferShape<TShape extends ShapeRecord> = {
+    [K in keyof TShape]: InferSchema<TShape[K]>;
+};
+declare class ObjectSchema<TShape extends ShapeRecord> extends BaseSchema<InferShape<TShape>> {
+    readonly shape: TShape;
+    constructor(shape: TShape);
+}
+type SchemaBuilder = {
+    <TShape extends ShapeRecord>(shape: TShape): ObjectSchema<TShape>;
+    string(): StringSchema;
+    number(): NumberSchema;
+    boolean(): BooleanSchema;
+    file(): FileSchema;
+};
+export declare const schema: SchemaBuilder;
+export declare function validateSchemaInput<T>(schemaDef: SchemaType<T> | undefined, args: unknown[]): unknown[];
+export declare function parseRpcArgsPayload(payload: string | null): any[];
+export {};

package/dist/runtime/schema.js

@@ -0,0 +1,148 @@
+export class SchemaValidationError extends Error {
+    isSchemaValidationError = true;
+    status = 400;
+    constructor(message) {
+        super(message);
+        this.name = 'SchemaValidationError';
+    }
+}
+function formatPath(path) {
+    return path || 'value';
+}
+function describe(value) {
+    if (value === null)
+        return 'null';
+    if (typeof File !== 'undefined' && value instanceof File)
+        return 'file';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+function fail(path, message) {
+    throw new SchemaValidationError(`${formatPath(path)} ${message}`);
+}
+function isPlainObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value) && !(typeof File !== 'undefined' && value instanceof File);
+}
+class BaseSchema {
+    parser;
+    constructor(parser) {
+        this.parser = parser;
+    }
+    parse(input, path = 'value') {
+        return this.parser(input, path);
+    }
+    optional(defaultValue) {
+        return new BaseSchema((input, path) => {
+            if (typeof input === 'undefined')
+                return defaultValue;
+            return this.parse(input, path);
+        });
+    }
+    list() {
+        return new BaseSchema((input, path) => {
+            if (!Array.isArray(input))
+                fail(path, `must be an array, got ${describe(input)}`);
+            return input.map((item, index) => this.parse(item, `${path}[${index}]`));
+        });
+    }
+}
+class StringSchema extends BaseSchema {
+    constructor() {
+        super((input, path) => {
+            if (typeof input !== 'string')
+                fail(path, `must be a string, got ${describe(input)}`);
+            return input;
+        });
+    }
+    min(length) {
+        return new BaseSchema((input, path) => {
+            const value = this.parse(input, path);
+            if (value.length < length)
+                fail(path, `must be at least ${length} character(s)`);
+            return value;
+        });
+    }
+}
+class NumberSchema extends BaseSchema {
+    constructor() {
+        super((input, path) => {
+            if (typeof input !== 'number' || Number.isNaN(input))
+                fail(path, `must be a number, got ${describe(input)}`);
+            return input;
+        });
+    }
+    min(value) {
+        return new BaseSchema((input, path) => {
+            const parsed = this.parse(input, path);
+            if (parsed < value)
+                fail(path, `must be at least ${value}`);
+            return parsed;
+        });
+    }
+}
+class BooleanSchema extends BaseSchema {
+    constructor() {
+        super((input, path) => {
+            if (typeof input !== 'boolean')
+                fail(path, `must be a boolean, got ${describe(input)}`);
+            return input;
+        });
+    }
+}
+class FileSchema extends BaseSchema {
+    constructor() {
+        super((input, path) => {
+            if (typeof File === 'undefined' || !(input instanceof File))
+                fail(path, `must be a file, got ${describe(input)}`);
+            return input;
+        });
+    }
+}
+class ObjectSchema extends BaseSchema {
+    shape;
+    constructor(shape) {
+        super((input, path) => {
+            if (!isPlainObject(input))
+                fail(path, `must be an object, got ${describe(input)}`);
+            const out = {};
+            for (const key of Object.keys(shape)) {
+                out[key] = shape[key].parse(input[key], `${path}.${key}`);
+            }
+            return out;
+        });
+        this.shape = shape;
+    }
+}
+function createSchema(shape) {
+    return new ObjectSchema(shape);
+}
+export const schema = Object.assign(createSchema, {
+    string: () => new StringSchema(),
+    number: () => new NumberSchema(),
+    boolean: () => new BooleanSchema(),
+    file: () => new FileSchema(),
+});
+export function validateSchemaInput(schemaDef, args) {
+    if (!schemaDef)
+        return args;
+    if (args.length !== 1) {
+        throw new SchemaValidationError(`validated RPCs must receive exactly one argument object, got ${args.length}`);
+    }
+    return [schemaDef.parse(args[0], 'data')];
+}
+export function parseRpcArgsPayload(payload) {
+    if (!payload)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(payload);
+    }
+    catch {
+        throw new SchemaValidationError('args must be valid JSON');
+    }
+    if (!Array.isArray(parsed)) {
+        throw new SchemaValidationError('args must be a JSON array');
+    }
+    return parsed;
+}

package/dist/runtime/types.d.ts

@@ -34,6 +34,8 @@ export interface RouteModule {
     actions?: Record<string, (formData: FormData, env: Env, ctx: RouteContext) => Promise<any>>;
     /** RPC functions â€" callable from client via fetch */
     rpc?: Record<string, (args: any[], env: Env, ctx: RouteContext) => Promise<any>>;
+    /** Optional schemas for RPC inputs, keyed by function name */
+    rpcSchemas?: Record<string, any>;
     /** Render function â€" returns route HTML and optional head content from data */
     render: (data: Record<string, any>) => PageRenderOutput;
     /** Layout name (default: 'default') */

package/dist/runtime/validation.d.ts

@@ -0,0 +1,26 @@
+export declare class RpcValidationError extends Error {
+    readonly isRpcValidationError = true;
+    readonly status = 400;
+    constructor(message: string);
+}
+export interface Validator<T> {
+    parse(input: unknown, path?: string): T;
+}
+export type InferValidator<T extends Validator<any>> = T extends Validator<infer U> ? U : never;
+export declare const v: {
+    string(): Validator<string>;
+    number(): Validator<number>;
+    boolean(): Validator<boolean>;
+    literal<const T extends string | number | boolean | null>(expected: T): Validator<T>;
+    optional<T>(inner: Validator<T>): Validator<T | undefined>;
+    nullable<T>(inner: Validator<T>): Validator<T | null>;
+    array<T>(inner: Validator<T>): Validator<T[]>;
+    object<TShape extends Record<string, Validator<any>>>(shape: TShape): Validator<{ [K in keyof TShape]: InferValidator<TShape[K]>; }>;
+    tuple<TItems extends readonly Validator<any>[]>(items: TItems): Validator<{ [K in keyof TItems]: InferValidator<TItems[K]>; }>;
+    union<TItems extends readonly Validator<any>[]>(items: TItems): Validator<InferValidator<TItems[number]>>;
+};
+export declare function rpc<TArgs extends any[], TResult>(validator: Validator<TArgs>, handler: (...args: TArgs) => Promise<TResult> | TResult): ((...args: TArgs) => Promise<TResult> | TResult) & {
+    __kuratchiRpcValidator: Validator<TArgs>;
+};
+export declare function validateRpcArgs(fn: (...args: any[]) => Promise<unknown> | unknown, args: unknown[]): any[];
+export declare function parseRpcArgsPayload(payload: string | null): any[];