@kuratchi/js 0.0.3 → 0.0.5

package/dist/compiler/index.js

@@ -1,9 +1,10 @@
 /**
- * Compiler — scans a project's routes/ directory, parses .html files,
+ * Compiler â€" scans a project's routes/ directory, parses .html files,
  * and generates a single Worker entry point.
  */
 import { parseFile } from './parser.js';
 import { compileTemplate } from './template.js';
+import { transpileTypeScript } from './transpile.js';
 import { filePathToPattern } from '../runtime/router.js';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -31,10 +32,56 @@ function compactInlineJs(source) {
         .replace(/\s*([{}();,:])\s*/g, '$1')
         .trim();
 }
+function rewriteImportedFunctionCalls(source, fnToModule) {
+    let out = source;
+    for (const [fnName, moduleId] of Object.entries(fnToModule)) {
+        if (!/^[A-Za-z_$][\w$]*$/.test(fnName))
+            continue;
+        const callRegex = new RegExp(`\\b${fnName}\\s*\\(`, 'g');
+        out = out.replace(callRegex, `${moduleId}.${fnName}(`);
+    }
+    return out;
+}
+function rewriteWorkerEnvAliases(source, aliases) {
+    let out = source;
+    for (const alias of aliases) {
+        if (!/^[A-Za-z_$][\w$]*$/.test(alias))
+            continue;
+        const aliasRegex = new RegExp(`\\b${alias}\\b`, 'g');
+        out = out.replace(aliasRegex, '__env');
+    }
+    return out;
+}
+function parseNamedImportBindings(line) {
+    const namesMatch = line.match(/import\s*\{([^}]+)\}/);
+    if (!namesMatch)
+        return [];
+    return namesMatch[1]
+        .split(',')
+        .map(n => n.trim())
+        .filter(Boolean)
+        .map(n => {
+        const parts = n.split(/\s+as\s+/).map(p => p.trim()).filter(Boolean);
+        return parts[1] || parts[0] || '';
+    })
+        .filter(Boolean);
+}
+function filterClientImportsForServer(imports, neededFns) {
+    const selected = [];
+    for (const line of imports) {
+        const bindings = parseNamedImportBindings(line);
+        if (bindings.length === 0)
+            continue;
+        if (bindings.some(name => neededFns.has(name))) {
+            selected.push(line);
+        }
+    }
+    return selected;
+}
 /**
  * Compile a project's src/routes/ into .kuratchi/routes.js
  *
- * The generated module exports { app } — an object with a fetch() method
+ * The generated module exports { app } â€" an object with a fetch() method
  * that handles routing, load functions, form actions, and rendering.
  * Returns the path to .kuratchi/worker.js — the stable wrangler entry point that
  * re-exports everything from routes.js (default fetch handler + named DO class exports).
@@ -49,21 +96,21 @@ export function compile(options) {
     }
     // Discover all .html route files
     const routeFiles = discoverRoutes(routesDir);
-    // Component compilation cache — only compile components that are actually imported
+    // Component compilation cache â€" only compile components that are actually imported
     const libDir = path.join(srcDir, 'lib');
-    const compiledComponentCache = new Map(); // fileName → compiled function code
-    const componentStyleCache = new Map(); // fileName → escaped CSS string (or empty)
+    const compiledComponentCache = new Map(); // fileName â†' compiled function code
+    const componentStyleCache = new Map(); // fileName â†' escaped CSS string (or empty)
     // Tracks which prop names inside a component are used as action={propName}.
-    // e.g. db-studio uses action={runQueryAction} → stores 'runQueryAction'.
+    // e.g. db-studio uses action={runQueryAction} â†' stores 'runQueryAction'.
     // When the route passes runQueryAction={runAdminSqlQuery}, the compiler knows
     // to add 'runAdminSqlQuery' to the route's actionFunctions.
-    const componentActionCache = new Map(); // fileName → Set of action prop names
+    const componentActionCache = new Map(); // fileName â†' Set of action prop names
     function compileComponent(fileName) {
         if (compiledComponentCache.has(fileName))
             return compiledComponentCache.get(fileName);
         let filePath;
         let funcName;
-        // Package component: "@kuratchi/ui:badge" → resolve from package
+        // Package component: "@kuratchi/ui:badge" â†' resolve from package
         const pkgMatch = fileName.match(/^(@[^:]+):(.+)$/);
         if (pkgMatch) {
             const pkgName = pkgMatch[1]; // e.g. "@kuratchi/ui"
@@ -87,16 +134,19 @@ export function compile(options) {
         // Use parseFile to properly split the <script> block from the template, and to
         // separate component imports (import X from '@kuratchi/ui/x.html') from regular code.
         // This prevents import lines from being inlined verbatim in the compiled function body.
-        const compParsed = parseFile(rawSource);
+        const compParsed = parseFile(rawSource, { kind: 'component', filePath });
         // propsCode = script body with all import lines stripped out
         const propsCode = compParsed.script
             ? compParsed.script
                 .replace(/^\s*import[\s\S]*?from\s+['"][^'"]+['"]\s*;?/gm, '')
                 .trim()
             : '';
+        const transpiledPropsCode = propsCode
+            ? transpileTypeScript(propsCode, `component-script:${fileName}.ts`)
+            : '';
         // template source (parseFile already removes the <script> block)
         let source = compParsed.template;
-        // Extract optional <style> block — CSS is scoped and injected once per route at compile time
+        // Extract optional <style> block â€" CSS is scoped and injected once per route at compile time
         let styleBlock = '';
         const styleMatch = source.match(/<style[\s>][\s\S]*?<\/style>/i);
         if (styleMatch) {
@@ -124,8 +174,8 @@ export function compile(options) {
             : '';
         componentStyleCache.set(fileName, escapedStyle);
         // Replace <slot></slot> and <slot /> with children output
-        source = source.replace(/<slot\s*><\/slot>/g, '{=html props.children || ""}');
-        source = source.replace(/<slot\s*\/>/g, '{=html props.children || ""}');
+        source = source.replace(/<slot\s*><\/slot>/g, '{@raw props.children || ""}');
+        source = source.replace(/<slot\s*\/>/g, '{@raw props.children || ""}');
         // Build a sub-component map from the component's own component imports so that
         // <Alert>, <Badge>, <Dialog>, etc. get expanded instead of emitted as raw tags.
         const subComponentNames = new Map();
@@ -142,7 +192,7 @@ export function compile(options) {
             }
         }
         // Scan the component template for action={propName} uses.
-        // These prop names are "action props" — when the route passes actionProp={routeFn},
+        // These prop names are "action props" â€" when the route passes actionProp={routeFn},
         // the compiler knows to add routeFn to the route's actionFunctions so it ends up
         // in the route's actions map and can be dispatched at runtime.
         const actionPropNames = new Set();
@@ -157,12 +207,12 @@ export function compile(options) {
         // Insert scope open after 'let __html = "";' (first line of body) and scope close at end
         const bodyLines = body.split('\n');
         const scopedBody = [bodyLines[0], scopeOpen, ...bodyLines.slice(1), scopeClose].join('\n');
-        const fnBody = propsCode ? `${propsCode}\n  ${scopedBody}` : scopedBody;
+        const fnBody = transpiledPropsCode ? `${transpiledPropsCode}\n  ${scopedBody}` : scopedBody;
         const compiled = `function ${funcName}(props, __esc) {\n  ${fnBody}\n  return __html;\n}`;
         compiledComponentCache.set(fileName, compiled);
         return compiled;
     }
-    // App layout: src/routes/layout.html (convention — wraps all routes automatically)
+    // App layout: src/routes/layout.html (convention â€" wraps all routes automatically)
     const layoutFile = path.join(routesDir, 'layout.html');
     let compiledLayout = null;
     const layoutComponentNames = new Map();
@@ -444,6 +494,17 @@ export function compile(options) {
     if(!msg) return;
     if(!window.confirm(msg)){ e.preventDefault(); e.stopPropagation(); }
   }, true);
+  document.addEventListener('submit', function(e){
+    if(e.defaultPrevented) return;
+    var f = e.target;
+    if(!f || !f.querySelector) return;
+    var aInput = f.querySelector('input[name="_action"]');
+    if(!aInput) return;
+    var aName = aInput.value;
+    if(!aName) return;
+    f.setAttribute('data-action-loading', aName);
+    Array.prototype.slice.call(f.querySelectorAll('button[type="submit"],button:not([type="button"]):not([type="reset"])')).forEach(function(b){ b.disabled = true; });
+  }, true);
   document.addEventListener('change', function(e){
     var t = e.target;
     if(!t || !t.getAttribute) return;
@@ -458,21 +519,118 @@ export function compile(options) {
   }, true);
   by('[data-select-all]').forEach(function(m){ var g = m.getAttribute('data-select-all'); if(g) syncGroup(g); });
 })();`;
+        const reactiveRuntimeSource = `(function(g){
+  if(g.__kuratchiReactive) return;
+  const targetMap = new WeakMap();
+  const proxyMap = new WeakMap();
+  let active = null;
+  const queue = new Set();
+  let flushing = false;
+  function queueRun(fn){
+    queue.add(fn);
+    if(flushing) return;
+    flushing = true;
+    Promise.resolve().then(function(){
+      try {
+        const jobs = Array.from(queue);
+        queue.clear();
+        for (const job of jobs) job();
+      } finally {
+        flushing = false;
+      }
+    });
+  }
+  function cleanup(effect){
+    const deps = effect.__deps || [];
+    for (const dep of deps) dep.delete(effect);
+    effect.__deps = [];
+  }
+  function track(target, key){
+    if(!active) return;
+    let depsMap = targetMap.get(target);
+    if(!depsMap){ depsMap = new Map(); targetMap.set(target, depsMap); }
+    let dep = depsMap.get(key);
+    if(!dep){ dep = new Set(); depsMap.set(key, dep); }
+    if(dep.has(active)) return;
+    dep.add(active);
+    if(!active.__deps) active.__deps = [];
+    active.__deps.push(dep);
+  }
+  function trigger(target, key){
+    const depsMap = targetMap.get(target);
+    if(!depsMap) return;
+    const effects = new Set();
+    const add = function(k){
+      const dep = depsMap.get(k);
+      if(dep) dep.forEach(function(e){ effects.add(e); });
+    };
+    add(key);
+    add('*');
+    effects.forEach(function(e){ queueRun(e); });
+  }
+  function isObject(value){ return value !== null && typeof value === 'object'; }
+  function proxify(value){
+    if(!isObject(value)) return value;
+    if(proxyMap.has(value)) return proxyMap.get(value);
+    const proxy = new Proxy(value, {
+      get(target, key, receiver){
+        track(target, key);
+        const out = Reflect.get(target, key, receiver);
+        return isObject(out) ? proxify(out) : out;
+      },
+      set(target, key, next, receiver){
+        const prev = target[key];
+        const result = Reflect.set(target, key, next, receiver);
+        if(prev !== next) trigger(target, key);
+        if(Array.isArray(target) && key !== 'length') trigger(target, 'length');
+        return result;
+      },
+      deleteProperty(target, key){
+        const had = Object.prototype.hasOwnProperty.call(target, key);
+        const result = Reflect.deleteProperty(target, key);
+        if(had) trigger(target, key);
+        return result;
+      }
+    });
+    proxyMap.set(value, proxy);
+    return proxy;
+  }
+  function effect(fn){
+    const run = function(){
+      cleanup(run);
+      active = run;
+      try { fn(); } finally { active = null; }
+    };
+    run.__deps = [];
+    run();
+    return function(){ cleanup(run); };
+  }
+  function state(initial){ return proxify(initial); }
+  function replace(_prev, next){ return proxify(next); }
+  g.__kuratchiReactive = { state, effect, replace };
+})(window);`;
         const actionScript = `<script>${options.isDev ? bridgeSource : compactInlineJs(bridgeSource)}</script>`;
+        const reactiveRuntimeScript = `<script>${options.isDev ? reactiveRuntimeSource : compactInlineJs(reactiveRuntimeSource)}</script>`;
+        if (source.includes('</head>')) {
+            source = source.replace('</head>', reactiveRuntimeScript + '\n</head>');
+        }
+        else {
+            source = reactiveRuntimeScript + '\n' + source;
+        }
         source = source.replace('</body>', actionScript + '\n</body>');
         // Parse layout for <script> block (component imports + data vars)
-        const layoutParsed = parseFile(source);
+        const layoutParsed = parseFile(source, { kind: 'layout', filePath: layoutFile });
         const hasLayoutScript = layoutParsed.script && (Object.keys(layoutParsed.componentImports).length > 0 || layoutParsed.hasLoad);
         if (hasLayoutScript) {
-            // Dynamic layout — has component imports and/or data declarations
+            // Dynamic layout â€" has component imports and/or data declarations
             // Compile component imports from layout
             for (const [pascalName, fileName] of Object.entries(layoutParsed.componentImports)) {
                 compileComponent(fileName);
                 layoutComponentNames.set(pascalName, fileName);
             }
             // Replace <slot></slot> with content parameter injection
-            let layoutTemplate = layoutParsed.template.replace(/<slot\s*><\/slot>/g, '{=html __content}');
-            layoutTemplate = layoutTemplate.replace(/<slot\s*\/>/g, '{=html __content}');
+            let layoutTemplate = layoutParsed.template.replace(/<slot\s*><\/slot>/g, '{@raw __content}');
+            layoutTemplate = layoutTemplate.replace(/<slot\s*\/>/g, '{@raw __content}');
             // Build layout action names so action={fn} works in layouts
             const layoutActionNames = new Set(layoutParsed.actionFunctions);
             // Compile the layout template with component + action support
@@ -500,7 +658,7 @@ export function compile(options) {
 }`;
         }
         else {
-            // Static layout — no components, use fast string split (original behavior)
+            // Static layout â€" no components, use fast string split (original behavior)
             const slotMarker = '<slot></slot>';
             const slotIdx = source.indexOf(slotMarker);
             if (slotIdx === -1) {
@@ -513,7 +671,7 @@ export function compile(options) {
         }
     }
     // Custom error pages: src/routes/NNN.html (e.g. 404.html, 500.html, 401.html, 403.html)
-    // Only compiled if the user explicitly creates them — otherwise the framework's built-in default is used
+    // Only compiled if the user explicitly creates them â€" otherwise the framework's built-in default is used
     const compiledErrorPages = new Map();
     for (const file of fs.readdirSync(routesDir)) {
         const match = file.match(/^(\d{3})\.html$/);
@@ -573,16 +731,130 @@ export function compile(options) {
             }
         }
     }
+    const resolveExistingModuleFile = (absBase) => {
+        const candidates = [
+            absBase,
+            absBase + '.ts',
+            absBase + '.js',
+            absBase + '.mjs',
+            absBase + '.cjs',
+            path.join(absBase, 'index.ts'),
+            path.join(absBase, 'index.js'),
+            path.join(absBase, 'index.mjs'),
+            path.join(absBase, 'index.cjs'),
+        ];
+        for (const candidate of candidates) {
+            if (fs.existsSync(candidate) && fs.statSync(candidate).isFile())
+                return candidate;
+        }
+        return null;
+    };
+    const toModuleSpecifier = (fromFileAbs, toFileAbs) => {
+        let rel = path.relative(path.dirname(fromFileAbs), toFileAbs).replace(/\\/g, '/');
+        if (!rel.startsWith('.'))
+            rel = './' + rel;
+        return rel;
+    };
+    const transformedServerModules = new Map();
+    const modulesOutDir = path.join(projectDir, '.kuratchi', 'modules');
+    const resolveDoProxyTarget = (absPath) => {
+        const normalizedNoExt = absPath.replace(/\\/g, '/').replace(/\.[^.\/]+$/, '');
+        const proxyNoExt = doHandlerProxyPaths.get(normalizedNoExt);
+        if (!proxyNoExt)
+            return null;
+        return resolveExistingModuleFile(proxyNoExt) ?? (fs.existsSync(proxyNoExt + '.js') ? proxyNoExt + '.js' : null);
+    };
+    const resolveImportTarget = (importerAbs, spec) => {
+        if (spec.startsWith('$')) {
+            const slashIdx = spec.indexOf('/');
+            const folder = slashIdx === -1 ? spec.slice(1) : spec.slice(1, slashIdx);
+            const rest = slashIdx === -1 ? '' : spec.slice(slashIdx + 1);
+            if (!folder)
+                return null;
+            const abs = path.join(srcDir, folder, rest);
+            return resolveExistingModuleFile(abs) ?? abs;
+        }
+        if (spec.startsWith('.')) {
+            const abs = path.resolve(path.dirname(importerAbs), spec);
+            return resolveExistingModuleFile(abs) ?? abs;
+        }
+        return null;
+    };
+    const transformServerModule = (entryAbsPath) => {
+        const resolved = resolveExistingModuleFile(entryAbsPath) ?? entryAbsPath;
+        const normalized = resolved.replace(/\\/g, '/');
+        const cached = transformedServerModules.get(normalized);
+        if (cached)
+            return cached;
+        const relFromProject = path.relative(projectDir, resolved);
+        const outPath = path.join(modulesOutDir, relFromProject);
+        transformedServerModules.set(normalized, outPath);
+        const outDir = path.dirname(outPath);
+        if (!fs.existsSync(outDir))
+            fs.mkdirSync(outDir, { recursive: true });
+        if (!/\.(ts|js|mjs|cjs)$/i.test(resolved) || !fs.existsSync(resolved)) {
+            const passthrough = resolved;
+            transformedServerModules.set(normalized, passthrough);
+            return passthrough;
+        }
+        const source = fs.readFileSync(resolved, 'utf-8');
+        const rewriteSpecifier = (spec) => {
+            const target = resolveImportTarget(resolved, spec);
+            if (!target)
+                return spec;
+            const doProxyTarget = resolveDoProxyTarget(target);
+            if (doProxyTarget)
+                return toModuleSpecifier(outPath, doProxyTarget);
+            const normalizedTarget = target.replace(/\\/g, '/');
+            const inProject = normalizedTarget.startsWith(projectDir.replace(/\\/g, '/') + '/');
+            if (!inProject)
+                return spec;
+            const targetResolved = resolveExistingModuleFile(target) ?? target;
+            if (!/\.(ts|js|mjs|cjs)$/i.test(targetResolved))
+                return spec;
+            const rewrittenTarget = transformServerModule(targetResolved);
+            return toModuleSpecifier(outPath, rewrittenTarget);
+        };
+        let rewritten = source.replace(/(from\s+)(['"])([^'"]+)\2/g, (_m, p1, q, spec) => {
+            return `${p1}${q}${rewriteSpecifier(spec)}${q}`;
+        });
+        rewritten = rewritten.replace(/(import\s*\(\s*)(['"])([^'"]+)\2(\s*\))/g, (_m, p1, q, spec, p4) => {
+            return `${p1}${q}${rewriteSpecifier(spec)}${q}${p4}`;
+        });
+        writeIfChanged(outPath, rewritten);
+        return outPath;
+    };
+    const resolveCompiledImportPath = (origPath, importerDir, outFileDir) => {
+        const isBareModule = !origPath.startsWith('.') && !origPath.startsWith('/') && !origPath.startsWith('$');
+        if (isBareModule)
+            return origPath;
+        let absImport;
+        if (origPath.startsWith('$')) {
+            const slashIdx = origPath.indexOf('/');
+            const folder = slashIdx === -1 ? origPath.slice(1) : origPath.slice(1, slashIdx);
+            const rest = slashIdx === -1 ? '' : origPath.slice(slashIdx + 1);
+            absImport = path.join(srcDir, folder, rest);
+        }
+        else {
+            absImport = path.resolve(importerDir, origPath);
+        }
+        const doProxyTarget = resolveDoProxyTarget(absImport);
+        const target = doProxyTarget ?? transformServerModule(absImport);
+        let relPath = path.relative(outFileDir, target).replace(/\\/g, '/');
+        if (!relPath.startsWith('.'))
+            relPath = './' + relPath;
+        return relPath;
+    };
     // Parse and compile each route
     const compiledRoutes = [];
     const allImports = [];
     let moduleCounter = 0;
-    // Layout server import resolution — resolve non-component imports to module IDs
+    // Layout server import resolution â€" resolve non-component imports to module IDs
     let isLayoutAsync = false;
     let compiledLayoutActions = null;
     if (compiledLayout && fs.existsSync(path.join(routesDir, 'layout.html'))) {
         const layoutSource = fs.readFileSync(path.join(routesDir, 'layout.html'), 'utf-8');
-        const layoutParsedForImports = parseFile(layoutSource);
+        const layoutParsedForImports = parseFile(layoutSource, { kind: 'layout', filePath: layoutFile });
         if (layoutParsedForImports.serverImports.length > 0) {
             const layoutFileDir = routesDir;
             const outFileDir = path.join(projectDir, '.kuratchi');
@@ -592,39 +864,7 @@ export function compile(options) {
                 if (!pathMatch)
                     continue;
                 const origPath = pathMatch[1];
-                const isBareModule = !origPath.startsWith('.') && !origPath.startsWith('/') && !origPath.startsWith('$');
-                let importPath;
-                if (isBareModule) {
-                    importPath = origPath;
-                }
-                else {
-                    let absImport;
-                    if (origPath.startsWith('$')) {
-                        const slashIdx = origPath.indexOf('/');
-                        const folder = origPath.slice(1, slashIdx);
-                        const rest = origPath.slice(slashIdx + 1);
-                        absImport = path.join(srcDir, folder, rest);
-                        // Redirect DO handler imports to generated proxy modules
-                        const doProxyPath = doHandlerProxyPaths.get(absImport.replace(/\\/g, '/'));
-                        if (doProxyPath) {
-                            absImport = doProxyPath;
-                        }
-                    }
-                    else {
-                        absImport = path.resolve(layoutFileDir, origPath);
-                    }
-                    let relPath = path.relative(outFileDir, absImport).replace(/\\/g, '/');
-                    if (!relPath.startsWith('.'))
-                        relPath = './' + relPath;
-                    let resolvedExt = '';
-                    for (const ext of ['.ts', '.js', '/index.ts', '/index.js']) {
-                        if (fs.existsSync(absImport + ext)) {
-                            resolvedExt = ext;
-                            break;
-                        }
-                    }
-                    importPath = relPath + resolvedExt;
-                }
+                const importPath = resolveCompiledImportPath(origPath, layoutFileDir, outFileDir);
                 const moduleId = `__m${moduleCounter++}`;
                 allImports.push(`import * as ${moduleId} from '${importPath}';`);
                 const namesMatch = imp.match(/import\s*\{([^}]+)\}/);
@@ -665,7 +905,7 @@ export function compile(options) {
                 }
             }
         }
-        // Detect if the compiled layout uses await → make it async
+        // Detect if the compiled layout uses await â†' make it async
         isLayoutAsync = /\bawait\b/.test(compiledLayout);
         if (isLayoutAsync) {
             compiledLayout = compiledLayout.replace(/^function __layout\(/, 'async function __layout(');
@@ -674,72 +914,62 @@ export function compile(options) {
     for (let i = 0; i < routeFiles.length; i++) {
         const rf = routeFiles[i];
         const fullPath = path.join(routesDir, rf.file);
-        const source = fs.readFileSync(fullPath, 'utf-8');
-        const parsed = parseFile(source);
         const pattern = filePathToPattern(rf.name);
-        // Build a mapping: functionName → moduleId for all imports in this route
+        // -- API route (index.ts / index.js) --
+        if (rf.type === 'api') {
+            const outFileDir = path.join(projectDir, '.kuratchi');
+            // Resolve the route file's absolute path through transformServerModule
+            // so that $-prefixed imports inside it get rewritten correctly
+            const absRoutePath = transformServerModule(fullPath);
+            let importPath = path.relative(outFileDir, absRoutePath).replace(/\\/g, '/');
+            if (!importPath.startsWith('.'))
+                importPath = './' + importPath;
+            const moduleId = `__m${moduleCounter++}`;
+            allImports.push(`import * as ${moduleId} from '${importPath}';`);
+            // Scan the source for exported method handlers (only include what exists)
+            const apiSource = fs.readFileSync(fullPath, 'utf-8');
+            const allMethods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
+            const exportedMethods = allMethods.filter(m => {
+                // Match: export function GET, export async function GET, export { ... as GET }
+                const fnPattern = new RegExp(`export\\s+(async\\s+)?function\\s+${m}\\b`);
+                const reExportPattern = new RegExp(`export\\s*\\{[^}]*\\b\\w+\\s+as\\s+${m}\\b`);
+                const namedExportPattern = new RegExp(`export\\s*\\{[^}]*\\b${m}\\b`);
+                return fnPattern.test(apiSource) || reExportPattern.test(apiSource) || namedExportPattern.test(apiSource);
+            });
+            const methodEntries = exportedMethods
+                .map(m => `${m}: ${moduleId}.${m}`)
+                .join(', ');
+            compiledRoutes.push(`{ pattern: '${pattern}', __api: true, ${methodEntries} }`);
+            continue;
+        }
+        // ── Page route (page.html) ──
+        const source = fs.readFileSync(fullPath, 'utf-8');
+        const parsed = parseFile(source, { kind: 'route', filePath: fullPath });
+        // Build a mapping: functionName â†' moduleId for all imports in this route
         const fnToModule = {};
         const outFileDir = path.join(projectDir, '.kuratchi');
-        if (parsed.serverImports.length > 0) {
+        const neededServerFns = new Set([
+            ...parsed.actionFunctions,
+            ...parsed.pollFunctions,
+            ...parsed.dataGetQueries.map((q) => q.fnName),
+        ]);
+        const routeServerImports = parsed.serverImports.length > 0
+            ? parsed.serverImports
+            : filterClientImportsForServer(parsed.clientImports, neededServerFns);
+        if (routeServerImports.length > 0) {
             const routeFileDir = path.dirname(fullPath);
-            for (const imp of parsed.serverImports) {
+            for (const imp of routeServerImports) {
                 const pathMatch = imp.match(/from\s+['"]([^'"]+)['"]/);
                 if (!pathMatch)
                     continue;
                 const origPath = pathMatch[1];
-                // Bare module specifiers (packages) — pass through as-is
-                const isBareModule = !origPath.startsWith('.') && !origPath.startsWith('/') && !origPath.startsWith('$');
-                let importPath;
-                if (isBareModule) {
-                    // Package import: @kuratchi/auth, KuratchiJS, cloudflare:workers, etc.
-                    importPath = origPath;
-                }
-                else {
-                    let absImport;
-                    if (origPath.startsWith('$')) {
-                        // Dynamic $folder/ alias → src/folder/
-                        const slashIdx = origPath.indexOf('/');
-                        const folder = origPath.slice(1, slashIdx);
-                        const rest = origPath.slice(slashIdx + 1);
-                        absImport = path.join(srcDir, folder, rest);
-                        // Redirect DO handler imports to generated proxy modules
-                        const doProxyPath = doHandlerProxyPaths.get(absImport.replace(/\\/g, '/'));
-                        if (doProxyPath) {
-                            absImport = doProxyPath;
-                        }
-                    }
-                    else {
-                        // Resolve the import relative to the route file
-                        absImport = path.resolve(routeFileDir, origPath);
-                    }
-                    // Make it relative to the output directory
-                    let relPath = path.relative(outFileDir, absImport).replace(/\\/g, '/');
-                    if (!relPath.startsWith('.'))
-                        relPath = './' + relPath;
-                    // Check if the resolved file exists (try .ts, .js extensions)
-                    let resolvedExt = '';
-                    for (const ext of ['.ts', '.js', '/index.ts', '/index.js']) {
-                        if (fs.existsSync(absImport + ext)) {
-                            resolvedExt = ext;
-                            break;
-                        }
-                    }
-                    importPath = relPath + resolvedExt;
-                }
+                // Bare module specifiers (packages) â€" pass through as-is
+                const importPath = resolveCompiledImportPath(origPath, routeFileDir, outFileDir);
                 const moduleId = `__m${moduleCounter++}`;
                 allImports.push(`import * as ${moduleId} from '${importPath}';`);
                 // Extract named imports and map them to this module
-                const namesMatch = imp.match(/import\s*\{([^}]+)\}/);
-                if (namesMatch) {
-                    const names = namesMatch[1]
-                        .split(',')
-                        .map(n => n.trim())
-                        .filter(Boolean)
-                        .map(n => {
-                        const parts = n.split(/\s+as\s+/).map(p => p.trim()).filter(Boolean);
-                        return parts[1] || parts[0] || '';
-                    })
-                        .filter(Boolean);
+                const names = parseNamedImportBindings(imp);
+                if (names.length > 0) {
                     for (const name of names) {
                         fnToModule[name] = moduleId;
                     }
@@ -752,7 +982,7 @@ export function compile(options) {
             }
         }
         // Build per-route component names from explicit imports
-        // componentImports: { StatCard: 'stat-card' } → componentNames maps PascalCase → fileName
+        // componentImports: { StatCard: 'stat-card' } â†' componentNames maps PascalCase â†' fileName
         const routeComponentNames = new Map();
         for (const [pascalName, fileName] of Object.entries(parsed.componentImports)) {
             // Compile the component on first use
@@ -767,22 +997,22 @@ export function compile(options) {
         // We then scan the route template for that component's usage and extract the bound values.
         for (const [pascalName, compFileName] of routeComponentNames.entries()) {
             const actionPropNames = componentActionCache.get(compFileName);
-            if (!actionPropNames || actionPropNames.size === 0)
-                continue;
             // Find all usages of <PascalName ...> in the route template and extract prop bindings.
             // Match <ComponentName ... propName={value} ... > across multiple lines.
             const compTagRegex = new RegExp(`<${pascalName}\\b([\\s\\S]*?)/>`, 'g');
             for (const tagMatch of parsed.template.matchAll(compTagRegex)) {
                 const attrs = tagMatch[1];
-                for (const propName of actionPropNames) {
-                    // Find propName={identifier} binding
-                    const propRegex = new RegExp(`\\b${propName}=\\{([A-Za-z_$][\\w$]*)\\}`);
-                    const propMatch = attrs.match(propRegex);
-                    if (propMatch) {
-                        const routeFnName = propMatch[1];
-                        // Only add if this function is actually imported by the route
-                        if (routeFnName in fnToModule && !parsed.actionFunctions.includes(routeFnName)) {
-                            parsed.actionFunctions.push(routeFnName);
+                if (actionPropNames && actionPropNames.size > 0) {
+                    for (const propName of actionPropNames) {
+                        // Find propName={identifier} binding
+                        const propRegex = new RegExp(`\\b${propName}=\\{([A-Za-z_$][\\w$]*)\\}`);
+                        const propMatch = attrs.match(propRegex);
+                        if (propMatch) {
+                            const routeFnName = propMatch[1];
+                            // Only add if this function is actually imported by the route
+                            if (routeFnName in fnToModule && !parsed.actionFunctions.includes(routeFnName)) {
+                                parsed.actionFunctions.push(routeFnName);
+                            }
                         }
                     }
                 }
@@ -791,7 +1021,7 @@ export function compile(options) {
         // Compile template to render function body (pass component names and action names)
         // An identifier is a valid server action if it is either:
         //   1. Directly imported (present in fnToModule), or
-        //   2. A top-level script declaration (present in dataVars) — covers cases like
+        //   2. A top-level script declaration (present in dataVars) â€" covers cases like
         //      `const fn = importedFn` or `async function fn() {}` where the binding
         //      is locally declared but delegates to an imported function.
         const dataVarsSet = new Set(parsed.dataVars);
@@ -869,7 +1099,16 @@ export function compile(options) {
     // Collect only the components that were actually imported by routes
     const compiledComponents = Array.from(compiledComponentCache.values());
     // Generate the routes module
-    const runtimeImportPath = resolveRuntimeImportPath(projectDir);
+    const rawRuntimeImportPath = resolveRuntimeImportPath(projectDir);
+    let runtimeImportPath;
+    if (rawRuntimeImportPath) {
+        // Resolve the runtime file's absolute path and pass it through transformServerModule
+        // so that $durable-objects/* and other project imports get rewritten to their proxies.
+        const runtimeAbs = path.resolve(path.join(projectDir, '.kuratchi'), rawRuntimeImportPath);
+        const transformedRuntimePath = transformServerModule(runtimeAbs);
+        const outFile = options.outFile ?? path.join(projectDir, '.kuratchi', 'routes.js');
+        runtimeImportPath = toModuleSpecifier(outFile, transformedRuntimePath);
+    }
     const hasRuntime = !!runtimeImportPath;
     const output = generateRoutesModule({
         projectDir,
@@ -887,7 +1126,7 @@ export function compile(options) {
         isLayoutAsync,
         compiledLayoutActions,
         hasRuntime,
-        runtimeImportPath: runtimeImportPath ?? undefined,
+        runtimeImportPath,
     });
     // Write to .kuratchi/routes.js
     const outFile = options.outFile ?? path.join(projectDir, '.kuratchi', 'routes.js');
@@ -919,7 +1158,7 @@ export function compile(options) {
     writeIfChanged(workerFile, workerLines.join('\n'));
     return workerFile;
 }
-// ── Helpers ─────────────────────────────────────────────────────────────
+// â"€â"€ Helpers â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€
 /**
  * Write a file only if its content has changed.
  * Prevents unnecessary filesystem events that would retrigger wrangler's file watcher.
@@ -1013,7 +1252,7 @@ function readUiTheme(projectDir) {
         console.warn('[kuratchi] ui.theme: "default" configured but @kuratchi/ui theme.css not found');
         return null;
     }
-    // Custom path — resolve relative to project root
+    // Custom path â€" resolve relative to project root
     const customPath = path.resolve(projectDir, themeValue);
     if (fs.existsSync(customPath)) {
         return fs.readFileSync(customPath, 'utf-8');
@@ -1031,7 +1270,7 @@ function resolvePackageComponent(projectDir, pkgName, componentFile) {
     if (fs.existsSync(nmPath))
         return nmPath;
     // 2. Try workspace layout: project is in apps/X or packages/X, sibling packages in packages/
-    // @kuratchi/ui → kuratchi-ui (convention: scope stripped, slash → dash)
+    // @kuratchi/ui â†' kuratchi-ui (convention: scope stripped, slash â†' dash)
     const pkgDirName = pkgName.replace(/^@/, '').replace(/\//g, '-');
     const workspaceRoot = path.resolve(projectDir, '../..');
     const wsPath = path.join(workspaceRoot, 'packages', pkgDirName, 'src', 'lib', componentFile + '.html');
@@ -1069,32 +1308,49 @@ function discoverRoutes(routesDir) {
         for (const entry of entries) {
             if (entry.isDirectory()) {
                 const childPrefix = prefix ? `${prefix}/${entry.name}` : entry.name;
-                // Folder-based route: routes/db/page.html → /db
+                // Folder-based page route: routes/db/page.html → /db
                 const pageFile = path.join(dir, entry.name, 'page.html');
                 if (fs.existsSync(pageFile)) {
                     const routeFile = `${childPrefix}/page.html`;
                     if (!registered.has(routeFile)) {
                         registered.add(routeFile);
-                        results.push({ file: routeFile, name: childPrefix, layouts: getLayoutsForPrefix(childPrefix) });
+                        results.push({ file: routeFile, name: childPrefix, layouts: getLayoutsForPrefix(childPrefix), type: 'page' });
+                    }
+                }
+                // Folder-based API route: routes/api/v1/health/index.ts -> /api/v1/health
+                const apiFile = ['index.ts', 'index.js'].find(f => fs.existsSync(path.join(dir, entry.name, f)));
+                if (apiFile && !fs.existsSync(pageFile)) {
+                    const routeFile = `${childPrefix}/${apiFile}`;
+                    if (!registered.has(routeFile)) {
+                        registered.add(routeFile);
+                        results.push({ file: routeFile, name: childPrefix, layouts: [], type: 'api' });
                     }
                 }
                 // Always recurse into subdirectory (for nested routes like /admin/roles)
                 walk(path.join(dir, entry.name), childPrefix);
             }
             else if (entry.name === 'layout.html' || entry.name === '404.html' || entry.name === '500.html') {
-                // Skip — layout.html is the app layout, 404/500 are error pages, not routes
+                // Skip — layout.html is the app layout, 404/500 are error pages, not routes
                 continue;
             }
+            else if (entry.name === 'index.ts' || entry.name === 'index.js') {
+                // API route file in current directory -> index API route for this prefix
+                const routeFile = prefix ? `${prefix}/${entry.name}` : entry.name;
+                if (!registered.has(routeFile)) {
+                    registered.add(routeFile);
+                    results.push({ file: routeFile, name: prefix || 'index', layouts: [], type: 'api' });
+                }
+            }
             else if (entry.name === 'page.html') {
-                // page.html in current directory → index route for this prefix
+                // page.html in current directory → index route for this prefix
                 const routeFile = prefix ? `${prefix}/page.html` : 'page.html';
                 if (!registered.has(routeFile)) {
                     registered.add(routeFile);
-                    results.push({ file: routeFile, name: prefix || 'index', layouts: getLayoutsForPrefix(prefix) });
+                    results.push({ file: routeFile, name: prefix || 'index', layouts: getLayoutsForPrefix(prefix), type: 'page' });
                 }
             }
             else if (entry.name.endsWith('.html') && entry.name !== 'page.html') {
-                // File-based route: routes/about.html → /about (fallback)
+                // File-based route: routes/about.html → /about (fallback)
                 const name = prefix
                     ? `${prefix}/${entry.name.replace('.html', '')}`
                     : entry.name.replace('.html', '');
@@ -1102,6 +1358,7 @@ function discoverRoutes(routesDir) {
                     file: prefix ? `${prefix}/${entry.name}` : entry.name,
                     name,
                     layouts: getLayoutsForPrefix(prefix),
+                    type: 'page',
                 });
             }
         }
@@ -1120,18 +1377,48 @@ function buildRouteObject(opts) {
     const hasFns = Object.keys(fnToModule).length > 0;
     const parts = [];
     parts.push(`    pattern: '${pattern}'`);
-    // Load function — generated from the script block's top-level code + data-get queries
+    const queryVars = parsed.dataGetQueries?.map((q) => q.asName) ?? [];
+    let scriptBody = parsed.script
+        ? parsed.script.replace(/^\s*import[\s\S]*?from\s+['"][^'"]+['"]\s*;?/gm, '').trim()
+        : '';
+    scriptBody = rewriteImportedFunctionCalls(scriptBody, fnToModule);
+    scriptBody = rewriteWorkerEnvAliases(scriptBody, parsed.workerEnvAliases);
+    let explicitLoadFunction = parsed.loadFunction
+        ? parsed.loadFunction.replace(/^export\s+/, '').trim()
+        : '';
+    if (explicitLoadFunction) {
+        explicitLoadFunction = rewriteImportedFunctionCalls(explicitLoadFunction, fnToModule);
+        explicitLoadFunction = rewriteWorkerEnvAliases(explicitLoadFunction, parsed.workerEnvAliases);
+    }
+    if (explicitLoadFunction && /\bawait\b/.test(scriptBody)) {
+        throw new Error(`[kuratchi compiler] ${pattern}\nTop-level await cannot be mixed with export async function load(). Move async server work into load().`);
+    }
+    if (scriptBody) {
+        scriptBody = transpileTypeScript(scriptBody, `route-script:${pattern}.ts`);
+    }
+    if (explicitLoadFunction) {
+        explicitLoadFunction = transpileTypeScript(explicitLoadFunction, `route-load:${pattern}.ts`);
+    }
+    const scriptUsesAwait = /\bawait\b/.test(scriptBody);
+    const scriptReturnVars = parsed.script
+        ? parsed.dataVars.filter((v) => !queryVars.includes(v))
+        : [];
+    // Load function â€" internal server prepass for async route script bodies
+    // and data-get query state hydration.
     const hasDataGetQueries = Array.isArray(parsed.dataGetQueries) && parsed.dataGetQueries.length > 0;
-    if ((parsed.hasLoad && parsed.script) || hasDataGetQueries) {
-        // Get script body (everything except imports)
-        let body = parsed.script
-            ? parsed.script.replace(/^\s*import[\s\S]*?from\s+['"][^'"]+['"]\s*;?/gm, '').trim()
-            : '';
+    if (explicitLoadFunction) {
+        parts.push(`    load: ${explicitLoadFunction}`);
+    }
+    else if ((scriptBody && scriptUsesAwait) || hasDataGetQueries) {
+        let loadBody = '';
+        if (scriptBody && scriptUsesAwait) {
+            loadBody = scriptBody;
+        }
         // Inject data-get query state blocks into load scope.
         // Each query exposes:
         //   { state, loading, error, data, empty, success }
+        const queries = parsed.dataGetQueries;
         if (hasDataGetQueries) {
-            const queries = parsed.dataGetQueries;
             const queryLines = [];
             for (const q of queries) {
                 const fnName = q.fnName;
@@ -1154,25 +1441,13 @@ function buildRouteObject(opts) {
                 queryLines.push(`  }`);
                 queryLines.push(`}`);
             }
-            body = [body, queryLines.join('\n')].filter(Boolean).join('\n');
+            loadBody = [loadBody, queryLines.join('\n')].filter(Boolean).join('\n');
         }
-        // Rewrite imported function calls: fnName( → __mN.fnName(
-        // Rewrite imported function calls to use the module namespace
-        for (const [fnName, moduleId] of Object.entries(fnToModule)) {
-            if (!/^[A-Za-z_$][\w$]*$/.test(fnName))
-                continue;
-            const callRegex = new RegExp(`\\b${fnName}\\s*\\(`, 'g');
-            body = body.replace(callRegex, `${moduleId}.${fnName}(`);
-        }
-        // Determine if body uses await
-        const isAsync = /\bawait\b/.test(body) || hasDataGetQueries;
-        // Return an object with all declared data variables
-        const returnObj = parsed.dataVars.length > 0
-            ? `\n      return { ${parsed.dataVars.join(', ')} };`
-            : '';
-        parts.push(`    ${isAsync ? 'async ' : ''}load(params = {}) {\n      ${body}${returnObj}\n    }`);
+        const loadReturnVars = [...scriptReturnVars, ...queryVars];
+        const returnObj = loadReturnVars.length > 0 ? `\n      return { ${loadReturnVars.join(', ')} };` : '';
+        parts.push(`    async load(params = {}) {\n      ${loadBody}${returnObj}\n    }`);
     }
-    // Actions — functions referenced via action={fn} in the template
+    // Actions â€" functions referenced via action={fn} in the template
     if (hasFns && parsed.actionFunctions.length > 0) {
         const actionEntries = parsed.actionFunctions
             .map(fn => {
@@ -1182,7 +1457,7 @@ function buildRouteObject(opts) {
             .join(', ');
         parts.push(`    actions: { ${actionEntries} }`);
     }
-    // RPC — functions referenced via data-poll={fn(args)} in the template
+    // RPC â€" functions referenced via data-poll={fn(args)} in the template
     if (hasFns && parsed.pollFunctions.length > 0) {
         const rpcEntries = parsed.pollFunctions
             .map(fn => {
@@ -1193,12 +1468,21 @@ function buildRouteObject(opts) {
             .join(', ');
         parts.push(`    rpc: { ${rpcEntries} }`);
     }
-    // Render function — template compiled to JS with native flow control
+    // Render function â€" template compiled to JS with native flow control
     // Destructure data vars so templates reference them directly (e.g., {todos} not {data.todos})
-    // Always include __error so templates can show form action errors via {__error}
-    const allVars = [...parsed.dataVars];
-    if (!allVars.includes('__error'))
-        allVars.push('__error');
+    // Auto-inject action state objects so templates can reference signIn.error, signIn.loading, etc.
+    const renderPrelude = (scriptBody && !scriptUsesAwait) ? scriptBody : '';
+    const allVars = [...queryVars];
+    if (scriptUsesAwait) {
+        for (const v of scriptReturnVars) {
+            if (!allVars.includes(v))
+                allVars.push(v);
+        }
+    }
+    for (const fn of parsed.actionFunctions) {
+        if (!allVars.includes(fn))
+            allVars.push(fn);
+    }
     if (!allVars.includes('params'))
         allVars.push('params');
     if (!allVars.includes('breadcrumbs'))
@@ -1213,7 +1497,7 @@ function buildRouteObject(opts) {
         finalRenderBody = [lines[0], ...styleLines, ...lines.slice(1)].join('\n');
     }
     parts.push(`    render(data) {
-      ${destructure}${finalRenderBody}
+      ${destructure}${renderPrelude ? renderPrelude + '\n      ' : ''}${finalRenderBody}
       return __html;
     }`);
     return `  {\n${parts.join(',\n')}\n  }`;
@@ -1227,7 +1511,7 @@ function readOrmConfig(projectDir) {
     if (!ormBlock)
         return [];
     // Extract schema imports: import { todoSchema } from './src/schemas/todo';
-    const importMap = new Map(); // exportName → importPath
+    const importMap = new Map(); // exportName â†' importPath
     const importRegex = /import\s*\{\s*([^}]+)\s*\}\s*from\s*['"]([^'"]+)['"]/g;
     let m;
     while ((m = importRegex.exec(source)) !== null) {
@@ -1364,7 +1648,7 @@ function readDoConfig(projectDir) {
             if (list.length > 0)
                 entry.files = list;
         }
-        // (inject config removed — DO methods are org-scoped, no auto-injection needed)
+        // (inject config removed â€" DO methods are org-scoped, no auto-injection needed)
         entries.push(entry);
     }
     // Match string shorthand: BINDING: 'ClassName' (skip bindings already found)
@@ -1482,9 +1766,9 @@ function discoverFilesWithSuffix(dir, suffix) {
     return out;
 }
 /**
- * Scan for files that extend kuratchiDO.
- * Primary discovery is recursive under `src/server` for files ending in `.do.ts`.
- * Legacy fallback keeps `src/durable-objects/*.ts` compatible.
+ * Scan DO handler files.
+ * - Class mode: default class extends kuratchiDO
+ * - Function mode: exported functions in *.do.ts files (compiler wraps into DO class)
  */
 function discoverDoHandlers(srcDir, doConfig, ormDatabases) {
     const serverDir = path.join(srcDir, 'server');
@@ -1512,14 +1796,15 @@ function discoverDoHandlers(srcDir, doConfig, ormDatabases) {
     for (const absPath of discoveredFiles) {
         const file = path.basename(absPath);
         const source = fs.readFileSync(absPath, 'utf-8');
-        // Check if this file extends kuratchiDO
-        if (!/extends\s+kuratchiDO\b/.test(source))
+        const exportedFunctions = extractExportedFunctions(source);
+        const hasClass = /extends\s+kuratchiDO\b/.test(source);
+        if (!hasClass && exportedFunctions.length === 0)
             continue;
-        // Extract class name: export default class Sites extends kuratchiDO
+        // Extract class name when class mode is used.
         const classMatch = source.match(/export\s+default\s+class\s+(\w+)\s+extends\s+kuratchiDO/);
-        if (!classMatch)
+        const className = classMatch?.[1] ?? null;
+        if (hasClass && !className)
             continue;
-        const className = classMatch[1];
         // Binding resolution:
         // 1) explicit static binding in class
         // 2) config-mapped file name (supports .do.ts convention)
@@ -1544,10 +1829,8 @@ function discoverDoHandlers(srcDir, doConfig, ormDatabases) {
             continue;
         if (!bindings.has(binding))
             continue;
-        // Extract class methods — find the class body and parse method declarations
-        const classMethods = extractClassMethods(source, className);
-        // Extract named exports (custom worker-side helpers)
-        const namedExports = extractNamedExports(source);
+        // Extract class methods in class mode
+        const classMethods = className ? extractClassMethods(source, className) : [];
         const fileName = file.replace(/\.ts$/, '');
         const existing = fileNameToAbsPath.get(fileName);
         if (existing && existing !== absPath) {
@@ -1558,9 +1841,10 @@ function discoverDoHandlers(srcDir, doConfig, ormDatabases) {
             fileName,
             absPath,
             binding,
-            className,
+            mode: hasClass ? 'class' : 'function',
+            className: className ?? undefined,
             classMethods,
-            namedExports,
+            exportedFunctions,
         });
     }
     return handlers;
@@ -1652,40 +1936,33 @@ function extractClassMethods(source, className) {
     }
     return methods;
 }
-/**
- * Extract explicitly exported function/const names from a file.
- */
-function extractNamedExports(source) {
-    const exports = [];
-    // export async function name / export function name
+function extractExportedFunctions(source) {
+    const out = [];
     const fnRegex = /export\s+(?:async\s+)?function\s+(\w+)/g;
     let m;
     while ((m = fnRegex.exec(source)) !== null)
-        exports.push(m[1]);
-    // export const name
-    const constRegex = /export\s+const\s+(\w+)/g;
-    while ((m = constRegex.exec(source)) !== null)
-        exports.push(m[1]);
-    return exports;
+        out.push(m[1]);
+    return out;
 }
 /**
  * Generate a proxy module for a DO handler file.
  *
- * The proxy provides:
- *   - Auto-RPC function exports for each public class method
- *   - Re-exports of the user's custom named exports
- *
- * Methods that collide with custom exports are skipped (user's export wins).
+ * The proxy provides auto-RPC function exports.
+ * - Class mode: public class methods become RPC exports.
+ * - Function mode: exported functions become RPC exports, excluding lifecycle hooks.
  */
 function generateHandlerProxy(handler, projectDir) {
     const doDir = path.join(projectDir, '.kuratchi', 'do');
     const origRelPath = path.relative(doDir, handler.absPath).replace(/\\/g, '/').replace(/\.ts$/, '.js');
     const handlerLocal = `__handler_${toSafeIdentifier(handler.fileName)}`;
-    const customSet = new Set(handler.namedExports);
+    const lifecycle = new Set(['onInit', 'onAlarm', 'onMessage']);
+    const rpcFunctions = handler.mode === 'function'
+        ? handler.exportedFunctions.filter((n) => !lifecycle.has(n))
+        : handler.classMethods.filter((m) => m.visibility === 'public').map((m) => m.name);
     const methods = handler.classMethods.map((m) => ({ ...m }));
     const methodMap = new Map(methods.map((m) => [m.name, m]));
     let changed = true;
-    while (changed) {
+    while (changed && handler.mode === 'class') {
         changed = false;
         for (const m of methods) {
             if (m.hasWorkerContextCalls)
@@ -1700,15 +1977,56 @@ function generateHandlerProxy(handler, projectDir) {
             }
         }
     }
-    const publicMethods = methods.filter((m) => m.visibility === 'public').map((m) => m.name);
-    const workerContextMethods = methods
-        .filter((m) => m.visibility === 'public' && m.hasWorkerContextCalls)
-        .map((m) => m.name);
-    const asyncMethods = methods.filter((m) => m.isAsync).map((m) => m.name);
+    const workerContextMethods = handler.mode === 'class'
+        ? methods.filter((m) => m.visibility === 'public' && m.hasWorkerContextCalls).map((m) => m.name)
+        : [];
+    const asyncMethods = handler.mode === 'class'
+        ? methods.filter((m) => m.isAsync).map((m) => m.name)
+        : [];
     const lines = [
-        `// Auto-generated by KuratchiJS compiler — do not edit.`,
+        `// Auto-generated by KuratchiJS compiler â€" do not edit.`,
         `import { __getDoStub } from '${RUNTIME_DO_IMPORT}';`,
-        `import ${handlerLocal} from '${origRelPath}';`,
+        ...(handler.mode === 'class' ? [`import ${handlerLocal} from '${origRelPath}';`] : []),
+        ``,
+        `const __FD_TAG = '__kuratchi_form_data__';`,
+        `function __isPlainObject(__v) {`,
+        `  if (!__v || typeof __v !== 'object') return false;`,
+        `  const __proto = Object.getPrototypeOf(__v);`,
+        `  return __proto === Object.prototype || __proto === null;`,
+        `}`,
+        `function __encodeArg(__v, __seen = new WeakSet()) {`,
+        `  if (typeof FormData !== 'undefined' && __v instanceof FormData) {`,
+        `    return { [__FD_TAG]: Array.from(__v.entries()) };`,
+        `  }`,
+        `  if (Array.isArray(__v)) return __v.map((__x) => __encodeArg(__x, __seen));`,
+        `  if (__isPlainObject(__v)) {`,
+        `    if (__seen.has(__v)) throw new Error('[KuratchiJS] Circular object passed to DO RPC');`,
+        `    __seen.add(__v);`,
+        `    const __out = {};`,
+        `    for (const [__k, __val] of Object.entries(__v)) __out[__k] = __encodeArg(__val, __seen);`,
+        `    __seen.delete(__v);`,
+        `    return __out;`,
+        `  }`,
+        `  return __v;`,
+        `}`,
+        `function __decodeArg(__v) {`,
+        `  if (Array.isArray(__v)) return __v.map(__decodeArg);`,
+        `  if (__isPlainObject(__v)) {`,
+        `    const __obj = __v;`,
+        `    if (__FD_TAG in __obj) {`,
+        `      const __fd = new FormData();`,
+        `      const __entries = Array.isArray(__obj[__FD_TAG]) ? __obj[__FD_TAG] : [];`,
+        `      for (const __pair of __entries) {`,
+        `        if (Array.isArray(__pair) && __pair.length >= 2) __fd.append(String(__pair[0]), __pair[1]);`,
+        `      }`,
+        `      return __fd;`,
+        `    }`,
+        `    const __out = {};`,
+        `    for (const [__k, __val] of Object.entries(__obj)) __out[__k] = __decodeArg(__val);`,
+        `    return __out;`,
+        `  }`,
+        `  return __v;`,
+        `}`,
         ``,
     ];
     if (workerContextMethods.length > 0) {
@@ -1728,29 +2046,22 @@ function generateHandlerProxy(handler, projectDir) {
         lines.push(`      if (typeof __local === 'function' && !__asyncMethods.has(__k)) {`);
         lines.push(`        return (...__a) => __local.apply(__self, __a);`);
         lines.push(`      }`);
-        lines.push(`      return async (...__a) => { const __s = await __getDoStub('${handler.binding}'); if (!__s) throw new Error('Not authenticated'); return __s[__k](...__a); };`);
+        lines.push(`      return async (...__a) => { const __s = await __getDoStub('${handler.binding}'); if (!__s) throw new Error('Not authenticated'); return __s[__k](...__a.map((__x) => __encodeArg(__x))); };`);
         lines.push(`    },`);
         lines.push(`  });`);
-        lines.push(`  return ${handlerLocal}.prototype[__name].apply(__self, __args);`);
+        lines.push(`  return ${handlerLocal}.prototype[__name].apply(__self, __args.map(__decodeArg));`);
         lines.push(`}`);
         lines.push(``);
     }
-    // Export class methods (skip if a custom export has the same name)
-    for (const method of publicMethods) {
-        if (customSet.has(method))
-            continue; // user's export wins
+    // Export RPC methods
+    for (const method of rpcFunctions) {
         if (workerContextMethods.includes(method)) {
             lines.push(`export async function ${method}(...a) { return __callWorkerMethod('${method}', a); }`);
         }
         else {
-            lines.push(`export async function ${method}(...a) { const s = await __getDoStub('${handler.binding}'); if (!s) throw new Error('Not authenticated'); return s.${method}(...a); }`);
+            lines.push(`export async function ${method}(...a) { const s = await __getDoStub('${handler.binding}'); if (!s) throw new Error('Not authenticated'); return s.${method}(...a.map((__x) => __encodeArg(__x))); }`);
         }
     }
-    // Re-export custom named exports from the original file
-    if (handler.namedExports.length > 0) {
-        lines.push(``);
-        lines.push(`export { ${handler.namedExports.join(', ')} } from '${origRelPath}';`);
-    }
     return lines.join('\n') + '\n';
 }
 function generateRoutesModule(opts) {
@@ -1763,16 +2074,16 @@ function generateRoutesModule(opts) {
         .map(([status, fn]) => fn)
         .join('\n\n');
     // Resolve path to the framework's context module from the output directory
-    const contextImport = `import { __setRequestContext, __esc, __setLocal, __getLocals, buildDefaultBreadcrumbs as __buildDefaultBreadcrumbs } from '${RUNTIME_CONTEXT_IMPORT}';`;
+    const contextImport = `import { __setRequestContext, __esc, __rawHtml, __sanitizeHtml, __setLocal, __getLocals, buildDefaultBreadcrumbs as __buildDefaultBreadcrumbs } from '${RUNTIME_CONTEXT_IMPORT}';`;
     const runtimeImport = opts.hasRuntime && opts.runtimeImportPath
         ? `import __kuratchiRuntime from '${opts.runtimeImportPath}';`
         : '';
-    // Auth session init — thin cookie parsing injected into Worker entry
+    // Auth session init â€" thin cookie parsing injected into Worker entry
     let authInit = '';
     if (opts.authConfig && opts.authConfig.sessionEnabled) {
         const cookieName = opts.authConfig.cookieName;
         authInit = `
-// ── Auth Session Init ───────────────────────────────────────
+// â"€â"€ Auth Session Init â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€
 
 function __parseCookies(header) {
   const map = {};
@@ -1823,7 +2134,7 @@ function __initAuth(request) {
                 ...schemaImports,
             ].join('\n');
             migrationInit = `
-// ── ORM Auto-Migration ──────────────────────────────────────
+// â"€â"€ ORM Auto-Migration â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€
 
 let __migrated = false;
 const __ormDatabases = [
@@ -1857,7 +2168,7 @@ async function __runMigrations() {
 `;
         }
     }
-    // Auth plugin init — import config + call @kuratchi/auth setup functions
+    // Auth plugin init â€" import config + call @kuratchi/auth setup functions
     let authPluginImports = '';
     let authPluginInit = '';
     const ac = opts.authConfig;
@@ -1909,14 +2220,14 @@ async function __runMigrations() {
         }
         authPluginImports = imports.join('\n');
         authPluginInit = `
-// ── Auth Plugin Init ───────────────────────────────────────
+// â"€â"€ Auth Plugin Init â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€
 
 function __initAuthPlugins() {
 ${initLines.join('\n')}
 }
 `;
     }
-    // ── Durable Object class generation ───────────────────────────
+    // â"€â"€ Durable Object class generation â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€
     let doImports = '';
     let doClassCode = '';
     let doResolverInit = '';
@@ -1926,7 +2237,28 @@ ${initLines.join('\n')}
         const doResolverLines = [];
         doImportLines.push(`import { DurableObject as __DO } from 'cloudflare:workers';`);
         doImportLines.push(`import { initDO as __initDO } from '@kuratchi/orm';`);
-        doImportLines.push(`import { __registerDoResolver, __registerDoClassBinding } from '${RUNTIME_DO_IMPORT}';`);
+        doImportLines.push(`import { __registerDoResolver, __registerDoClassBinding, __setDoContext } from '${RUNTIME_DO_IMPORT}';`);
+        doImportLines.push(`const __DO_FD_TAG = '__kuratchi_form_data__';`);
+        doImportLines.push(`function __isDoPlainObject(__v) {`);
+        doImportLines.push(`  if (!__v || typeof __v !== 'object') return false;`);
+        doImportLines.push(`  const __proto = Object.getPrototypeOf(__v);`);
+        doImportLines.push(`  return __proto === Object.prototype || __proto === null;`);
+        doImportLines.push(`}`);
+        doImportLines.push(`function __decodeDoArg(__v) {`);
+        doImportLines.push(`  if (Array.isArray(__v)) return __v.map(__decodeDoArg);`);
+        doImportLines.push(`  if (__isDoPlainObject(__v)) {`);
+        doImportLines.push(`    if (__DO_FD_TAG in __v) {`);
+        doImportLines.push(`      const __fd = new FormData();`);
+        doImportLines.push(`      const __entries = Array.isArray(__v[__DO_FD_TAG]) ? __v[__DO_FD_TAG] : [];`);
+        doImportLines.push(`      for (const __pair of __entries) { if (Array.isArray(__pair) && __pair.length >= 2) __fd.append(String(__pair[0]), __pair[1]); }`);
+        doImportLines.push(`      return __fd;`);
+        doImportLines.push(`    }`);
+        doImportLines.push(`    const __out = {};`);
+        doImportLines.push(`    for (const [__k, __val] of Object.entries(__v)) __out[__k] = __decodeDoArg(__val);`);
+        doImportLines.push(`    return __out;`);
+        doImportLines.push(`  }`);
+        doImportLines.push(`  return __v;`);
+        doImportLines.push(`}`);
         // We need getCurrentUser and getOrgStubByName for stub resolvers
         doImportLines.push(`import { getCurrentUser as __getCU, getOrgStubByName as __getOSBN } from '@kuratchi/auth';`);
         // Group handlers by binding
@@ -1940,6 +2272,10 @@ ${initLines.join('\n')}
         for (const doEntry of opts.doConfig) {
             const handlers = handlersByBinding.get(doEntry.binding) ?? [];
             const ormDb = opts.ormDatabases.find(d => d.binding === doEntry.binding);
+            const fnHandlers = handlers.filter((h) => h.mode === 'function');
+            const initHandlers = fnHandlers.filter((h) => h.exportedFunctions.includes('onInit'));
+            const alarmHandlers = fnHandlers.filter((h) => h.exportedFunctions.includes('onAlarm'));
+            const messageHandlers = fnHandlers.filter((h) => h.exportedFunctions.includes('onMessage'));
             // Import schema (paths are relative to project root; prefix ../ since we're in .kuratchi/)
             if (ormDb) {
                 const schemaPath = ormDb.schemaImportPath.replace(/^\.\//, '../');
@@ -1954,7 +2290,12 @@ ${initLines.join('\n')}
                 if (!handlerImportPath.startsWith('.'))
                     handlerImportPath = './' + handlerImportPath;
                 const handlerVar = `__handler_${toSafeIdentifier(h.fileName)}`;
-                doImportLines.push(`import ${handlerVar} from '${handlerImportPath}';`);
+                if (h.mode === 'class') {
+                    doImportLines.push(`import ${handlerVar} from '${handlerImportPath}';`);
+                }
+                else {
+                    doImportLines.push(`import * as ${handlerVar} from '${handlerImportPath}';`);
+                }
             }
             // Generate DO class
             doClassLines.push(`export class ${doEntry.className} extends __DO {`);
@@ -1963,6 +2304,11 @@ ${initLines.join('\n')}
             if (ormDb) {
                 doClassLines.push(`    this.db = __initDO(ctx.storage.sql, __doSchema_${doEntry.binding});`);
             }
+            for (const h of initHandlers) {
+                const handlerVar = `__handler_${toSafeIdentifier(h.fileName)}`;
+                doClassLines.push(`    __setDoContext(this);`);
+                doClassLines.push(`    Promise.resolve(${handlerVar}.onInit.call(this)).catch((err) => console.error('[kuratchi] DO onInit failed:', err?.message || err));`);
+            }
             doClassLines.push(`  }`);
             if (ormDb) {
                 doClassLines.push(`  async __kuratchiLogActivity(payload) {`);
@@ -2001,16 +2347,45 @@ ${initLines.join('\n')}
                 doClassLines.push(`    return rows;`);
                 doClassLines.push(`  }`);
             }
+            // Function-mode lifecycle dispatchers
+            if (alarmHandlers.length > 0) {
+                doClassLines.push(`  async alarm(...args) {`);
+                doClassLines.push(`    __setDoContext(this);`);
+                for (const h of alarmHandlers) {
+                    const handlerVar = `__handler_${toSafeIdentifier(h.fileName)}`;
+                    doClassLines.push(`    await ${handlerVar}.onAlarm.call(this, ...args);`);
+                }
+                doClassLines.push(`  }`);
+            }
+            if (messageHandlers.length > 0) {
+                doClassLines.push(`  webSocketMessage(...args) {`);
+                doClassLines.push(`    __setDoContext(this);`);
+                for (const h of messageHandlers) {
+                    const handlerVar = `__handler_${toSafeIdentifier(h.fileName)}`;
+                    doClassLines.push(`    ${handlerVar}.onMessage.call(this, ...args);`);
+                }
+                doClassLines.push(`  }`);
+            }
             doClassLines.push(`}`);
-            // Apply handler methods to prototype
+            // Apply handler methods to prototype (outside class body)
             for (const h of handlers) {
                 const handlerVar = `__handler_${toSafeIdentifier(h.fileName)}`;
-                doClassLines.push(`for (const __k of Object.getOwnPropertyNames(${handlerVar}.prototype)) { if (__k !== 'constructor') ${doEntry.className}.prototype[__k] = ${handlerVar}.prototype[__k]; }`);
-                doResolverLines.push(`  __registerDoClassBinding(${handlerVar}, '${doEntry.binding}');`);
+                if (h.mode === 'class') {
+                    doClassLines.push(`for (const __k of Object.getOwnPropertyNames(${handlerVar}.prototype)) { if (__k !== 'constructor') ${doEntry.className}.prototype[__k] = function(...__a){ __setDoContext(this); return ${handlerVar}.prototype[__k].apply(this, __a.map(__decodeDoArg)); }; }`);
+                    doResolverLines.push(`  __registerDoClassBinding(${handlerVar}, '${doEntry.binding}');`);
+                }
+                else {
+                    const lifecycle = new Set(['onInit', 'onAlarm', 'onMessage']);
+                    for (const fn of h.exportedFunctions) {
+                        if (lifecycle.has(fn))
+                            continue;
+                        doClassLines.push(`${doEntry.className}.prototype[${JSON.stringify(fn)}] = function(...__a){ __setDoContext(this); return ${handlerVar}.${fn}.apply(this, __a.map(__decodeDoArg)); };`);
+                    }
+                }
             }
             // Register stub resolver
             if (doEntry.stubId) {
-                // Config-driven: e.g. stubId: 'user.orgId' → __u.orgId
+                // Config-driven: e.g. stubId: 'user.orgId' â†' __u.orgId
                 const fieldPath = doEntry.stubId.startsWith('user.') ? `__u.${doEntry.stubId.slice(5)}` : doEntry.stubId;
                 const checkField = doEntry.stubId.startsWith('user.') ? doEntry.stubId.slice(5) : doEntry.stubId;
                 doResolverLines.push(`  __registerDoResolver('${doEntry.binding}', async () => {`);
@@ -2020,37 +2395,37 @@ ${initLines.join('\n')}
                 doResolverLines.push(`  });`);
             }
             else {
-                // No stubId config — stub must be obtained manually
-                doResolverLines.push(`  // No 'stubId' config for ${doEntry.binding} — stub must be obtained manually`);
+                // No stubId config â€" stub must be obtained manually
+                doResolverLines.push(`  // No 'stubId' config for ${doEntry.binding} â€" stub must be obtained manually`);
             }
         }
         doImports = doImportLines.join('\n');
-        doClassCode = `\n// ── Durable Object Classes (generated) ──────────────────────────\n\n` + doClassLines.join('\n') + '\n';
+        doClassCode = `\n// â"€â"€ Durable Object Classes (generated) â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€\n\n` + doClassLines.join('\n') + '\n';
         doResolverInit = `\nfunction __initDoResolvers() {\n${doResolverLines.join('\n')}\n}\n`;
     }
-    return `// Generated by KuratchiJS compiler — do not edit.
+    return `// Generated by KuratchiJS compiler â€" do not edit.
 ${opts.isDev ? '\nglobalThis.__kuratchi_DEV__ = true;\n' : ''}
 ${workerImport}
 ${contextImport}
-${runtimeImport ? runtimeImport + '\n' : ''}${migrationImports ? migrationImports + '\n' : ''}${authPluginImports ? authPluginImports + '\n' : ''}${doImports ? doImports + '\n' : ''}${opts.serverImports.join('\n')}
+${runtimeImport ? runtimeImport + '\n' : ''}${migrationImports ? migrationImports + '\n' : ''}${authPluginImports ? authPluginImports + '\n' : ''}${doImports ? doImports + '\n' : ''}${opts.serverImports.join('\n')}
 
-// ── Assets ──────────────────────────────────────────────────────
+// â"€â"€ Assets â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€
 
 const __assets = {
 ${opts.compiledAssets.map(a => `  ${JSON.stringify(a.name)}: { content: ${JSON.stringify(a.content)}, mime: ${JSON.stringify(a.mime)}, etag: ${JSON.stringify(a.etag)} }`).join(',\n')}
 };
 
-// ── Router ──────────────────────────────────────────────────────
+// â"€â"€ Router â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€
 
-const __staticRoutes = new Map();  // exact path → index (O(1) lookup)
+const __staticRoutes = new Map();  // exact path â†' index (O(1) lookup)
 const __dynamicRoutes = [];        // regex-based routes (params/wildcards)
 
 function __addRoute(pattern, index) {
   if (!pattern.includes(':') && !pattern.includes('*')) {
-    // Static route — direct Map lookup, no regex needed
+    // Static route â€" direct Map lookup, no regex needed
     __staticRoutes.set(pattern, index);
   } else {
-    // Dynamic route — build regex for param extraction
+    // Dynamic route â€" build regex for param extraction
     const paramNames = [];
     let regexStr = pattern
       .replace(/\\*(\\w+)/g, (_, name) => { paramNames.push(name); return '(?<' + name + '>.+)'; })
@@ -2076,13 +2451,13 @@ function __match(pathname) {
   return null;
 }
 
-// ── Layout ──────────────────────────────────────────────────────
+// â"€â"€ Layout â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€
 
 ${layoutBlock}
 
 ${layoutActionsBlock}
 
-// ── Error pages ─────────────────────────────────────────────────
+// â"€â"€ Error pages â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€
 
 const __errorMessages = {
   400: 'Bad Request',
@@ -2097,7 +2472,7 @@ const __errorMessages = {
   503: 'Service Unavailable',
 };
 
-// Built-in default error page — clean, dark, minimal, centered
+// Built-in default error page â€" clean, dark, minimal, centered
 function __errorPage(status, detail) {
   const title = __errorMessages[status] || 'Error';
   const detailHtml = detail ? '<p style="font-family:ui-monospace,monospace;font-size:0.8rem;color:#555;background:#111;padding:0.5rem 1rem;border-radius:6px;max-width:480px;margin:1rem auto 0;word-break:break-word">' + __esc(detail) + '</p>' : '';
@@ -2119,8 +2494,8 @@ function __error(status, detail) {
   return __errorPage(status, detail);
 }
 
-${opts.compiledComponents.length > 0 ? '// ── Components ──────────────────────────────────────────────────\n\n' + opts.compiledComponents.join('\n\n') + '\n' : ''}${migrationInit}${authInit}${authPluginInit}${doResolverInit}${doClassCode}
-// ── Route definitions ───────────────────────────────────────────
+${opts.compiledComponents.length > 0 ? '// â"€â"€ Components â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€\n\n' + opts.compiledComponents.join('\n\n') + '\n' : ''}${migrationInit}${authInit}${authPluginInit}${doResolverInit}${doClassCode}
+// â"€â"€ Route definitions â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€
 
 const routes = [
 ${opts.compiledRoutes.join(',\n')}
@@ -2128,7 +2503,7 @@ ${opts.compiledRoutes.join(',\n')}
 
 for (let i = 0; i < routes.length; i++) __addRoute(routes[i].pattern, i);
 
-// ── Response helpers ────────────────────────────────────────────
+// â"€â"€ Response helpers â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€
 
 const __defaultSecHeaders = {
   'X-Content-Type-Options': 'nosniff',
@@ -2232,13 +2607,13 @@ async function __runRuntimeError(ctx, error) {
   return null;
 }
 
-// ── Exported Worker entrypoint ──────────────────────────────────
+// â"€â"€ Exported Worker entrypoint â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€
 
-export default class extends WorkerEntrypoint {
-  async fetch(request) {
-    __setRequestContext(this.ctx, request);
-    globalThis.__cloudflare_env__ = __env;
-${migrationInit ? '    await __runMigrations();\n' : ''}${authInit ? '    __initAuth(request);\n' : ''}${authPluginInit ? '    __initAuthPlugins();\n' : ''}${doResolverInit ? '    __initDoResolvers();\n' : ''}
+export default class extends WorkerEntrypoint {
+  async fetch(request) {
+    __setRequestContext(this.ctx, request);
+    globalThis.__cloudflare_env__ = __env;
+${migrationInit ? '    await __runMigrations();\n' : ''}${authInit ? '    __initAuth(request);\n' : ''}${authPluginInit ? '    __initAuthPlugins();\n' : ''}${doResolverInit ? '    __initDoResolvers();\n' : ''}
     const __runtimeCtx = {
       request,
       env: __env,
@@ -2277,6 +2652,24 @@ ${ac?.hasRateLimit ? '\n      // Rate limiting - check before route handlers\n
       __runtimeCtx.params = match.params;
       const route = routes[match.index];
       __setLocal('params', match.params);
+
+      // API route: dispatch to method handler
+      if (route.__api) {
+        const method = request.method;
+        if (method === 'OPTIONS') {
+          const handler = route['OPTIONS'];
+          if (typeof handler === 'function') return __secHeaders(await handler(__runtimeCtx));
+          const allowed = ['GET','POST','PUT','PATCH','DELETE','HEAD','OPTIONS'].filter(m => typeof route[m] === 'function').join(', ');
+          return __secHeaders(new Response(null, { status: 204, headers: { 'Allow': allowed, 'Access-Control-Allow-Methods': allowed } }));
+        }
+        const handler = route[method];
+        if (typeof handler !== 'function') {
+          const allowed = ['GET','POST','PUT','PATCH','DELETE','HEAD','OPTIONS'].filter(m => typeof route[m] === 'function').join(', ');
+          return __secHeaders(new Response(JSON.stringify({ error: 'Method Not Allowed' }), { status: 405, headers: { 'content-type': 'application/json', 'Allow': allowed } }));
+        }
+        return __secHeaders(await handler(__runtimeCtx));
+      }
+
       const __qFn = request.headers.get('x-kuratchi-query-fn') || '';
       const __qArgsRaw = request.headers.get('x-kuratchi-query-args') || '[]';
       let __qArgs = [];
@@ -2350,7 +2743,10 @@ ${ac?.hasRateLimit ? '\n      // Rate limiting - check before route handlers\n
             const data = (__loaded && typeof __loaded === 'object') ? __loaded : { value: __loaded };
             data.params = match.params;
             data.breadcrumbs = __getLocals().__breadcrumbs ?? [];
-            data.__error = (typeof __kuratchi_DEV__ !== 'undefined' && err && err.message) ? err.message : 'Action failed';
+            const __allActions = Object.assign({}, route.actions, __layoutActions || {});
+            Object.keys(__allActions).forEach(function(k) { if (!(k in data)) data[k] = { error: undefined, loading: false, success: false }; });
+            const __errMsg = (err && err.isActionError) ? err.message : (typeof __kuratchi_DEV__ !== 'undefined' && err && err.message) ? err.message : 'Action failed';
+            data[actionName] = { error: __errMsg, loading: false, success: false };
             return ${opts.isLayoutAsync ? 'await ' : ''}__render(route, data);
           }
           // Fetch-based actions return lightweight JSON (no page re-render)
@@ -2373,11 +2769,14 @@ ${ac?.hasRateLimit ? '\n      // Rate limiting - check before route handlers\n
         const data = (__loaded && typeof __loaded === 'object') ? __loaded : { value: __loaded };
         data.params = match.params;
         data.breadcrumbs = __getLocals().__breadcrumbs ?? [];
+        const __allActionsGet = Object.assign({}, route.actions, __layoutActions || {});
+        Object.keys(__allActionsGet).forEach(function(k) { if (!(k in data)) data[k] = { error: undefined, loading: false, success: false }; });
         return ${opts.isLayoutAsync ? 'await ' : ''}__render(route, data);
       } catch (err) {
         console.error('[kuratchi] Route load/render error:', err);
-        const __errDetail = typeof __kuratchi_DEV__ !== 'undefined' ? err.message : undefined;
-        return __secHeaders(new Response(${opts.isLayoutAsync ? 'await ' : ''}__layout(__error(500, __errDetail)), { status: 500, headers: { 'content-type': 'text/html; charset=utf-8' } }));
+        const __pageErrStatus = (err && err.isPageError && err.status) ? err.status : 500;
+        const __errDetail = (err && err.isPageError) ? err.message : (typeof __kuratchi_DEV__ !== 'undefined' && err && err.message) ? err.message : undefined;
+        return __secHeaders(new Response(${opts.isLayoutAsync ? 'await ' : ''}__layout(__error(__pageErrStatus, __errDetail)), { status: __pageErrStatus, headers: { 'content-type': 'text/html; charset=utf-8' } }));
       }
     };