@kuratchi/js 0.0.19 → 0.0.21

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/type-generator.d.ts

@@ -0,0 +1,8 @@
+export interface GenerateTypesOptions {
+    projectDir: string;
+    schemaPath?: string;
+    outputPath?: string;
+    localsInterface?: string;
+}
+export declare function generateAppTypes(options: GenerateTypesOptions): string;
+export declare function writeAppTypes(options: GenerateTypesOptions): void;

package/dist/compiler/type-generator.js

@@ -0,0 +1,124 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+function sqliteTypeToTs(sqlType) {
+    const lower = sqlType.toLowerCase();
+    if (lower.includes('integer') || lower.includes('int') || lower.includes('real') || lower.includes('numeric')) {
+        return 'number';
+    }
+    if (lower.includes('text') || lower.includes('varchar') || lower.includes('char')) {
+        return 'string';
+    }
+    if (lower.includes('blob')) {
+        return 'Uint8Array';
+    }
+    if (lower.includes('json')) {
+        return 'Record<string, unknown>';
+    }
+    if (lower.includes('boolean') || lower.includes('bool')) {
+        return 'boolean';
+    }
+    return 'unknown';
+}
+function parseSchemaColumn(name, definition) {
+    const lower = definition.toLowerCase();
+    const nullable = !lower.includes('not null');
+    const hasDefault = lower.includes('default');
+    const type = sqliteTypeToTs(definition);
+    return { name, type, nullable, hasDefault };
+}
+function parseSchemaFromSource(source) {
+    const tables = [];
+    // Match tables: { tableName: { col: 'def', ... }, ... }
+    const tablesMatch = source.match(/tables\s*:\s*\{([\s\S]*?)\n\t?\}/);
+    if (!tablesMatch)
+        return tables;
+    const tablesBlock = tablesMatch[1];
+    // Match each table definition
+    const tableRegex = /(\w+)\s*:\s*\{([^}]+)\}/g;
+    let match;
+    while ((match = tableRegex.exec(tablesBlock)) !== null) {
+        const tableName = match[1];
+        const columnsBlock = match[2];
+        const columns = [];
+        // Match each column: name: 'definition'
+        const colRegex = /(\w+)\s*:\s*['"]([^'"]+)['"]/g;
+        let colMatch;
+        while ((colMatch = colRegex.exec(columnsBlock)) !== null) {
+            columns.push(parseSchemaColumn(colMatch[1], colMatch[2]));
+        }
+        tables.push({ name: tableName, columns });
+    }
+    return tables;
+}
+function generateTableTypes(tables) {
+    const lines = [];
+    for (const table of tables) {
+        const pascalName = table.name
+            .split('_')
+            .map(s => s.charAt(0).toUpperCase() + s.slice(1))
+            .join('');
+        lines.push(`    /** Row type for ${table.name} table */`);
+        lines.push(`    interface ${pascalName}Row {`);
+        for (const col of table.columns) {
+            const optional = col.nullable || col.hasDefault ? '?' : '';
+            lines.push(`      ${col.name}${optional}: ${col.type};`);
+        }
+        lines.push(`    }`);
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+export function generateAppTypes(options) {
+    const { projectDir, schemaPath = 'src/server/schema.ts', outputPath = 'src/app.d.ts', localsInterface, } = options;
+    const schemaFullPath = path.join(projectDir, schemaPath);
+    let tables = [];
+    if (fs.existsSync(schemaFullPath)) {
+        const schemaSource = fs.readFileSync(schemaFullPath, 'utf-8');
+        tables = parseSchemaFromSource(schemaSource);
+    }
+    const tableTypes = tables.length > 0 ? generateTableTypes(tables) : '';
+    // Check if user has existing Locals definition to preserve
+    const outputFullPath = path.join(projectDir, outputPath);
+    let existingLocals = null;
+    if (fs.existsSync(outputFullPath)) {
+        const existing = fs.readFileSync(outputFullPath, 'utf-8');
+        // Extract user-defined Locals interface (between USER LOCALS START/END markers)
+        const localsMatch = existing.match(/\/\/ USER LOCALS START\n([\s\S]*?)\/\/ USER LOCALS END/);
+        if (localsMatch) {
+            existingLocals = localsMatch[1];
+        }
+    }
+    const localsBlock = existingLocals || localsInterface || `    interface Locals {
+      userId: number;
+      userEmail: string;
+    }`;
+    const output = `/**
+ * Type declarations for kuratchi app.
+ * 
+ * DB types are auto-generated from schema.ts - regenerate with: kuratchi types
+ * Edit the Locals interface below to match your runtime.hook.ts
+ */
+declare global {
+  namespace App {
+    /** Request-scoped locals set by runtime hooks */
+// USER LOCALS START
+${localsBlock}
+// USER LOCALS END
+
+${tableTypes ? `    // Database table row types (auto-generated from schema.ts)\n${tableTypes}` : ''}  }
+}
+
+export {};
+`;
+    return output;
+}
+export function writeAppTypes(options) {
+    const output = generateAppTypes(options);
+    const outputPath = path.join(options.projectDir, options.outputPath || 'src/app.d.ts');
+    const dir = path.dirname(outputPath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(outputPath, output, 'utf-8');
+    console.log(`[kuratchi] Generated types → ${path.relative(options.projectDir, outputPath)}`);
+}

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/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 */
@@ -37,7 +43,9 @@ export declare function getParam(name: string): string | undefined;
  * Throws a redirect signal consumed by the framework's PRG flow.
  */
 export declare function redirect(path: string, status?: number): never;
-/** Backward-compatible alias for redirect() */
+/**
+ * @deprecated Use redirect() instead. This alias will be removed in a future version.
+ */
 export declare function goto(path: string, status?: number): never;
 export declare function setBreadcrumbs(items: BreadcrumbItem[]): void;
 export declare function getBreadcrumbs(): BreadcrumbItem[];

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();
@@ -83,7 +104,9 @@ export function redirect(path, status = 303) {
     __locals.__redirectStatus = status;
     throw new RedirectError(path, status);
 }
-/** Backward-compatible alias for redirect() */
+/**
+ * @deprecated Use redirect() instead. This alias will be removed in a future version.
+ */
 export function goto(path, status = 303) {
     redirect(path, status);
 }

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/navigation.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Navigation helpers for kuratchi routes.
+ * Import via: import { redirect } from 'kuratchi:navigation';
+ *
+ * redirect() is server-side only — works in route scripts, server modules, and form actions.
+ * It throws a RedirectError that the framework catches and converts to a 303 redirect response.
+ */
+export { redirect } from './context.js';

package/dist/runtime/navigation.js

@@ -0,0 +1,8 @@
+/**
+ * Navigation helpers for kuratchi routes.
+ * Import via: import { redirect } from 'kuratchi:navigation';
+ *
+ * redirect() is server-side only — works in route scripts, server modules, and form actions.
+ * It throws a RedirectError that the framework catches and converts to a 303 redirect response.
+ */
+export { redirect } from './context.js';

package/dist/runtime/request.d.ts

@@ -1,3 +1,11 @@
+declare global {
+    namespace App {
+        /** Request-scoped locals set by runtime hooks. Extend in your app.d.ts */
+        interface Locals {
+            [key: string]: unknown;
+        }
+    }
+}
 export declare let url: URL;
 export declare let pathname: string;
 export declare let searchParams: URLSearchParams;
@@ -5,5 +13,25 @@ export declare let headers: Headers;
 export declare let method: string;
 export declare let params: Record<string, string>;
 export declare let slug: string | undefined;
+/**
+ * Get request-scoped locals with full type safety.
+ * Define your Locals type in src/app.d.ts:
+ * ```
+ * declare global {
+ *   namespace App {
+ *     interface Locals {
+ *       userId: number;
+ *       userEmail: string;
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare function getLocals(): App.Locals;
+/**
+ * Direct access to request-scoped locals.
+ * Type is inferred from App.Locals declared in your app.d.ts.
+ */
+export declare const locals: App.Locals;
 export declare function __setRequestState(request: Request): void;
 export declare function __setRequestParams(nextParams: Record<string, string> | null | undefined): void;

package/dist/runtime/request.js

@@ -1,3 +1,4 @@
+import { __getLocals } from './context.js';
 export let url = new URL('http://localhost/');
 export let pathname = '/';
 export let searchParams = url.searchParams;
@@ -5,6 +6,49 @@ export let headers = new Headers();
 export let method = 'GET';
 export let params = {};
 export let slug = undefined;
+/**
+ * Get request-scoped locals with full type safety.
+ * Define your Locals type in src/app.d.ts:
+ * ```
+ * declare global {
+ *   namespace App {
+ *     interface Locals {
+ *       userId: number;
+ *       userEmail: string;
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export function getLocals() {
+    return __getLocals();
+}
+/**
+ * Direct access to request-scoped locals.
+ * Type is inferred from App.Locals declared in your app.d.ts.
+ */
+export const locals = new Proxy({}, {
+    get(_target, prop) {
+        return __getLocals()[prop];
+    },
+    set(_target, prop, value) {
+        __getLocals()[prop] = value;
+        return true;
+    },
+    has(_target, prop) {
+        return prop in __getLocals();
+    },
+    ownKeys() {
+        return Reflect.ownKeys(__getLocals());
+    },
+    getOwnPropertyDescriptor(_target, prop) {
+        const locals = __getLocals();
+        if (prop in locals) {
+            return { configurable: true, enumerable: true, value: locals[prop] };
+        }
+        return undefined;
+    },
+});
 function __syncDerivedState() {
     pathname = url.pathname;
     searchParams = url.searchParams;