@kuratchi/js 0.0.2 → 0.0.4

package/dist/compiler/index.js

@@ -1,5 +1,5 @@
 /**
- * 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';
@@ -31,10 +31,36 @@ function compactInlineJs(source) {
         .replace(/\s*([{}();,:])\s*/g, '$1')
         .trim();
 }
+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 +75,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"
@@ -96,7 +122,7 @@ export function compile(options) {
             : '';
         // 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 +150,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 +168,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();
@@ -162,7 +188,7 @@ export function compile(options) {
         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 +470,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 +495,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 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 +634,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 +647,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$/);
@@ -531,6 +665,8 @@ export function compile(options) {
     const authConfig = readAuthConfig(projectDir);
     // Read Durable Object config and discover handler files
     const doConfig = readDoConfig(projectDir);
+    const containerConfig = readWorkerClassConfig(projectDir, 'containers');
+    const workflowConfig = readWorkerClassConfig(projectDir, 'workflows');
     const doHandlers = doConfig.length > 0
         ? discoverDoHandlers(srcDir, doConfig, ormDatabases)
         : [];
@@ -571,11 +707,125 @@ 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'))) {
@@ -590,39 +840,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*\{([^}]+)\}/);
@@ -663,7 +881,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(');
@@ -672,72 +890,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 pattern = filePathToPattern(rf.name);
+        // -- 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);
-        const pattern = filePathToPattern(rf.name);
-        // Build a mapping: functionName → moduleId for all imports in this route
+        // 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;
                     }
@@ -750,7 +958,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
@@ -765,22 +973,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);
+                            }
                         }
                     }
                 }
@@ -789,7 +997,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);
@@ -867,6 +1075,17 @@ 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 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,
         serverImports: allImports,
@@ -882,6 +1101,8 @@ export function compile(options) {
         isDev: options.isDev ?? false,
         isLayoutAsync,
         compiledLayoutActions,
+        hasRuntime,
+        runtimeImportPath,
     });
     // Write to .kuratchi/routes.js
     const outFile = options.outFile ?? path.join(projectDir, '.kuratchi', 'routes.js');
@@ -895,16 +1116,25 @@ export function compile(options) {
     // worker.js explicitly re-exports them so wrangler.jsonc can reference a
     // stable filename while routes.js is freely regenerated.
     const workerFile = path.join(outDir, 'worker.js');
+    const workerClassExports = [...containerConfig, ...workflowConfig]
+        .map((entry) => {
+        const importPath = toWorkerImportPath(projectDir, outDir, entry.file);
+        if (entry.exportKind === 'default') {
+            return `export { default as ${entry.className} } from '${importPath}';`;
+        }
+        return `export { ${entry.className} } from '${importPath}';`;
+    });
     const workerLines = [
         '// Auto-generated by kuratchi \u2014 do not edit.',
         "export { default } from './routes.js';",
         ...doConfig.map(c => `export { ${c.className} } from './routes.js';`),
+        ...workerClassExports,
         '',
     ];
     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.
@@ -998,7 +1228,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');
@@ -1016,7 +1246,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');
@@ -1054,32 +1284,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', '');
@@ -1087,6 +1334,7 @@ function discoverRoutes(routesDir) {
                     file: prefix ? `${prefix}/${entry.name}` : entry.name,
                     name,
                     layouts: getLayoutsForPrefix(prefix),
+                    type: 'page',
                 });
             }
         }
@@ -1105,18 +1353,33 @@ 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()
+        : '';
+    for (const [fnName, moduleId] of Object.entries(fnToModule)) {
+        if (!/^[A-Za-z_$][\w$]*$/.test(fnName))
+            continue;
+        const callRegex = new RegExp(`\\b${fnName}\\s*\\(`, 'g');
+        scriptBody = scriptBody.replace(callRegex, `${moduleId}.${fnName}(`);
+    }
+    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 ((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;
@@ -1139,25 +1402,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 => {
@@ -1167,7 +1418,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 => {
@@ -1178,12 +1429,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'))
@@ -1198,7 +1458,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  }`;
@@ -1212,7 +1472,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) {
@@ -1349,7 +1609,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)
@@ -1365,6 +1625,89 @@ function readDoConfig(projectDir) {
     }
     return entries;
 }
+function readWorkerClassConfig(projectDir, key) {
+    const configPath = path.join(projectDir, 'kuratchi.config.ts');
+    if (!fs.existsSync(configPath))
+        return [];
+    const source = fs.readFileSync(configPath, 'utf-8');
+    const keyIdx = source.search(new RegExp(`\\b${key}\\s*:\\s*\\{`));
+    if (keyIdx === -1)
+        return [];
+    const braceStart = source.indexOf('{', keyIdx);
+    if (braceStart === -1)
+        return [];
+    const body = extractBalancedBody(source, braceStart, '{', '}');
+    if (body == null)
+        return [];
+    const entries = [];
+    const expectedSuffix = key === 'containers' ? '.container' : '.workflow';
+    const allowedExt = /\.(ts|js|mjs|cjs)$/i;
+    const requiredFilePattern = new RegExp(`\\${expectedSuffix}\\.(ts|js|mjs|cjs)$`, 'i');
+    const resolveClassFromFile = (binding, filePath) => {
+        if (!requiredFilePattern.test(filePath)) {
+            throw new Error(`[kuratchi] ${key}.${binding} must reference a file ending in "${expectedSuffix}.ts|js|mjs|cjs". Received: ${filePath}`);
+        }
+        if (!allowedExt.test(filePath)) {
+            throw new Error(`[kuratchi] ${key}.${binding} file must be a TypeScript or JavaScript module. Received: ${filePath}`);
+        }
+        const absPath = path.isAbsolute(filePath) ? filePath : path.join(projectDir, filePath);
+        if (!fs.existsSync(absPath)) {
+            throw new Error(`[kuratchi] ${key}.${binding} file not found: ${filePath}`);
+        }
+        const fileSource = fs.readFileSync(absPath, 'utf-8');
+        const defaultClass = fileSource.match(/export\s+default\s+class\s+(\w+)/);
+        if (defaultClass) {
+            return { className: defaultClass[1], exportKind: 'default' };
+        }
+        const namedClass = fileSource.match(/export\s+class\s+(\w+)/);
+        if (namedClass) {
+            return { className: namedClass[1], exportKind: 'named' };
+        }
+        throw new Error(`[kuratchi] ${key}.${binding} must export a class via "export class X" or "export default class X". File: ${filePath}`);
+    };
+    // Object form:
+    // containers: { WORDPRESS_CONTAINER: { file: 'src/server/containers/wordpress.container.ts', className?: 'WordPressContainer' } }
+    // workflows:  { NEW_SITE_WORKFLOW: { file: 'src/server/workflows/new-site.workflow.ts', className?: 'NewSiteWorkflow' } }
+    const objRegex = /(\w+)\s*:\s*\{([^}]*(?:\{[^}]*\}[^}]*)*)\}/g;
+    let m;
+    while ((m = objRegex.exec(body)) !== null) {
+        const binding = m[1];
+        const entryBody = m[2];
+        const fileMatch = entryBody.match(/file\s*:\s*['"]([^'"]+)['"]/);
+        if (!fileMatch)
+            continue;
+        const inferred = resolveClassFromFile(binding, fileMatch[1]);
+        const classMatch = entryBody.match(/className\s*:\s*['"](\w+)['"]/);
+        const className = classMatch?.[1] ?? inferred.className;
+        entries.push({
+            binding,
+            className,
+            file: fileMatch[1],
+            exportKind: inferred.exportKind,
+        });
+    }
+    // String shorthand:
+    // containers: { WORDPRESS_CONTAINER: 'src/server/containers/wordpress.container.ts' }
+    // workflows:  { NEW_SITE_WORKFLOW: 'src/server/workflows/new-site.workflow.ts' }
+    const foundBindings = new Set(entries.map((e) => e.binding));
+    const pairRegex = /(\w+)\s*:\s*['"]([^'"]+)['"]\s*[,}\n]/g;
+    while ((m = pairRegex.exec(body)) !== null) {
+        const binding = m[1];
+        const file = m[2];
+        if (foundBindings.has(binding))
+            continue;
+        if (binding === 'file' || binding === 'className')
+            continue;
+        const inferred = resolveClassFromFile(binding, file);
+        entries.push({
+            binding,
+            className: inferred.className,
+            file,
+            exportKind: inferred.exportKind,
+        });
+    }
+    return entries;
+}
 function discoverFilesWithSuffix(dir, suffix) {
     if (!fs.existsSync(dir))
         return [];
@@ -1384,9 +1727,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');
@@ -1414,14 +1757,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)
@@ -1446,10 +1790,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) {
@@ -1460,9 +1802,10 @@ function discoverDoHandlers(srcDir, doConfig, ormDatabases) {
             fileName,
             absPath,
             binding,
-            className,
+            mode: hasClass ? 'class' : 'function',
+            className: className ?? undefined,
             classMethods,
-            namedExports,
+            exportedFunctions,
         });
     }
     return handlers;
@@ -1554,40 +1897,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)
@@ -1602,15 +1938,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) {
@@ -1630,29 +2007,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) {
@@ -1665,13 +2035,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}';`;
-    // Auth session init — thin cookie parsing injected into Worker entry
+    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
     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 = {};
@@ -1722,7 +2095,7 @@ function __initAuth(request) {
                 ...schemaImports,
             ].join('\n');
             migrationInit = `
-// ── ORM Auto-Migration ──────────────────────────────────────
+// â"€â"€ ORM Auto-Migration â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€
 
 let __migrated = false;
 const __ormDatabases = [
@@ -1756,7 +2129,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;
@@ -1808,14 +2181,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 = '';
@@ -1825,7 +2198,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
@@ -1839,6 +2233,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(/^\.\//, '../');
@@ -1853,7 +2251,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 {`);
@@ -1862,6 +2265,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) {`);
@@ -1900,16 +2308,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 () => {`);
@@ -1919,37 +2356,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}
-${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 + '>.+)'; })
@@ -1975,13 +2412,13 @@ function __match(pathname) {
   return null;
 }
 
-// ── Layout ──────────────────────────────────────────────────────
+// â"€â"€ Layout â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€
 
 ${layoutBlock}
 
 ${layoutActionsBlock}
 
-// ── Error pages ─────────────────────────────────────────────────
+// â"€â"€ Error pages â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€â"€
 
 const __errorMessages = {
   400: 'Bad Request',
@@ -1996,7 +2433,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>' : '';
@@ -2018,8 +2455,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')}
@@ -2027,7 +2464,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',
@@ -2075,141 +2512,269 @@ ${opts.isLayoutAsync ? 'async ' : ''}function __render(route, data) {
   return __attachCookies(new Response(${opts.isLayoutAsync ? 'await ' : ''}__layout(html), { headers: { 'content-type': 'text/html; charset=utf-8' } }));
 }
 
-// ── Exported Worker entrypoint ──────────────────────────────────
+const __runtimeDef = (typeof __kuratchiRuntime !== 'undefined' && __kuratchiRuntime && typeof __kuratchiRuntime === 'object') ? __kuratchiRuntime : {};
+const __runtimeEntries = Object.entries(__runtimeDef).filter(([, step]) => step && typeof step === 'object');
+
+async function __runRuntimeRequest(ctx, next) {
+  let idx = -1;
+  async function __dispatch(i) {
+    if (i <= idx) throw new Error('[kuratchi runtime] next() called multiple times in request phase');
+    idx = i;
+    const entry = __runtimeEntries[i];
+    if (!entry) return next();
+    const [, step] = entry;
+    if (typeof step.request !== 'function') return __dispatch(i + 1);
+    return await step.request(ctx, () => __dispatch(i + 1));
+  }
+  return __dispatch(0);
+}
+
+async function __runRuntimeRoute(ctx, next) {
+  let idx = -1;
+  async function __dispatch(i) {
+    if (i <= idx) throw new Error('[kuratchi runtime] next() called multiple times in route phase');
+    idx = i;
+    const entry = __runtimeEntries[i];
+    if (!entry) return next();
+    const [, step] = entry;
+    if (typeof step.route !== 'function') return __dispatch(i + 1);
+    return await step.route(ctx, () => __dispatch(i + 1));
+  }
+  return __dispatch(0);
+}
+
+async function __runRuntimeResponse(ctx, response) {
+  let out = response;
+  for (const [, step] of __runtimeEntries) {
+    if (typeof step.response !== 'function') continue;
+    out = await step.response(ctx, out);
+    if (!(out instanceof Response)) {
+      throw new Error('[kuratchi runtime] response handlers must return a Response');
+    }
+  }
+  return out;
+}
+
+async function __runRuntimeError(ctx, error) {
+  for (const [name, step] of __runtimeEntries) {
+    if (typeof step.error !== 'function') continue;
+    try {
+      const handled = await step.error(ctx, error);
+      if (handled instanceof Response) return handled;
+    } catch (hookErr) {
+      console.error('[kuratchi runtime] error handler failed in step', name, hookErr);
+    }
+  }
+  return null;
+}
+
+// â"€â"€ 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' : ''}
-    const url = new URL(request.url);
-${ac?.hasRateLimit ? '\n    // Rate limiting — check before route handlers\n    { const __rlRes = await __checkRL(); if (__rlRes) return __secHeaders(__rlRes); }\n' : ''}${ac?.hasTurnstile ? '    // Turnstile bot protection\n    { const __tsRes = await __checkTS(); if (__tsRes) return __secHeaders(__tsRes); }\n' : ''}${ac?.hasGuards ? '    // Route guards — redirect if not authenticated\n    { const __gRes = __checkGuard(); if (__gRes) return __secHeaders(__gRes); }\n' : ''}
+    const __runtimeCtx = {
+      request,
+      env: __env,
+      ctx: this.ctx,
+      url: new URL(request.url),
+      params: {},
+      locals: __getLocals(),
+    };
 
-    // Serve static assets from src/assets/ at /_assets/*
-    if (url.pathname.startsWith('/_assets/')) {
-      const name = url.pathname.slice('/_assets/'.length);
-      const asset = __assets[name];
-      if (asset) {
-        if (request.headers.get('if-none-match') === asset.etag) {
-          return new Response(null, { status: 304 });
+    const __coreFetch = async () => {
+      const request = __runtimeCtx.request;
+      const url = __runtimeCtx.url;
+${ac?.hasRateLimit ? '\n      // Rate limiting - check before route handlers\n      { const __rlRes = await __checkRL(); if (__rlRes) return __secHeaders(__rlRes); }\n' : ''}${ac?.hasTurnstile ? '      // Turnstile bot protection\n      { const __tsRes = await __checkTS(); if (__tsRes) return __secHeaders(__tsRes); }\n' : ''}${ac?.hasGuards ? '      // Route guards - redirect if not authenticated\n      { const __gRes = __checkGuard(); if (__gRes) return __secHeaders(__gRes); }\n' : ''}
+
+      // Serve static assets from src/assets/ at /_assets/*
+      if (url.pathname.startsWith('/_assets/')) {
+        const name = url.pathname.slice('/_assets/'.length);
+        const asset = __assets[name];
+        if (asset) {
+          if (request.headers.get('if-none-match') === asset.etag) {
+            return new Response(null, { status: 304 });
+          }
+          return new Response(asset.content, {
+            headers: { 'content-type': asset.mime, 'cache-control': 'public, max-age=31536000, immutable', 'etag': asset.etag }
+          });
         }
-        return new Response(asset.content, {
-          headers: { 'content-type': asset.mime, 'cache-control': 'public, max-age=31536000, immutable', 'etag': asset.etag }
-        });
+        return __secHeaders(new Response('Not Found', { status: 404 }));
       }
-      return __secHeaders(new Response('Not Found', { status: 404 }));
-    }
 
-    const match = __match(url.pathname);
+      const match = __match(url.pathname);
 
-    if (!match) {
-      return __secHeaders(new Response(${opts.isLayoutAsync ? 'await ' : ''}__layout(__error(404)), { status: 404, headers: { 'content-type': 'text/html; charset=utf-8' } }));
-    }
+      if (!match) {
+        return __secHeaders(new Response(${opts.isLayoutAsync ? 'await ' : ''}__layout(__error(404)), { status: 404, headers: { 'content-type': 'text/html; charset=utf-8' } }));
+      }
 
-    const route = routes[match.index];
-    __setLocal('params', match.params);
-    const __qFn = request.headers.get('x-kuratchi-query-fn') || '';
-    const __qArgsRaw = request.headers.get('x-kuratchi-query-args') || '[]';
-    let __qArgs = [];
-    try {
-      const __parsed = JSON.parse(__qArgsRaw);
-      __qArgs = Array.isArray(__parsed) ? __parsed : [];
-    } catch {}
-    __setLocal('__queryOverride', __qFn ? { fn: __qFn, args: __qArgs } : null);
-    if (!__getLocals().__breadcrumbs) {
-      __setLocal('breadcrumbs', __buildDefaultBreadcrumbs(url.pathname, match.params));
-    }
+      __runtimeCtx.params = match.params;
+      const route = routes[match.index];
+      __setLocal('params', match.params);
 
-    // RPC call: GET ?_rpc=fnName&_args=[...] → JSON response
-    const __rpcName = url.searchParams.get(‘_rpc’);
-    if (request.method === ‘GET’ && __rpcName && route.rpc && Object.hasOwn(route.rpc, __rpcName)) {
-      if (request.headers.get('x-kuratchi-rpc') !== '1') {
-        return __secHeaders(new Response(JSON.stringify({ ok: false, error: 'Forbidden' }), {
-          status: 403, headers: { 'content-type': 'application/json', 'cache-control': 'no-store' }
-        }));
-      }
-      try {
-        const __rpcArgsStr = url.searchParams.get('_args');
-        let __rpcArgs = [];
-        if (__rpcArgsStr) {
-          const __parsed = JSON.parse(__rpcArgsStr);
-          __rpcArgs = Array.isArray(__parsed) ? __parsed : [];
+      // 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 __rpcResult = await route.rpc[__rpcName](...__rpcArgs);
-        return __secHeaders(new Response(JSON.stringify({ ok: true, data: __rpcResult }), {
-          headers: { 'content-type': 'application/json', 'cache-control': 'no-store' }
-        }));
-      } catch (err) {
-        console.error('[kuratchi] RPC error:', err);
-        const __errMsg = typeof __kuratchi_DEV__ !== 'undefined' ? err.message : 'Internal Server Error';
-        return __secHeaders(new Response(JSON.stringify({ ok: false, error: __errMsg }), {
-          status: 500, headers: { 'content-type': 'application/json', 'cache-control': 'no-store' }
-        }));
+        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));
       }
-    }
 
-    // Form action: POST with hidden _action field in form body
-    if (request.method === 'POST') {
-      if (!__isSameOrigin(request, url)) {
-        return __secHeaders(new Response('Forbidden', { status: 403 }));
+      const __qFn = request.headers.get('x-kuratchi-query-fn') || '';
+      const __qArgsRaw = request.headers.get('x-kuratchi-query-args') || '[]';
+      let __qArgs = [];
+      try {
+        const __parsed = JSON.parse(__qArgsRaw);
+        __qArgs = Array.isArray(__parsed) ? __parsed : [];
+      } catch {}
+      __setLocal('__queryOverride', __qFn ? { fn: __qFn, args: __qArgs } : null);
+      if (!__getLocals().__breadcrumbs) {
+        __setLocal('breadcrumbs', __buildDefaultBreadcrumbs(url.pathname, match.params));
       }
-      const formData = await request.formData();
-      const actionName = formData.get('_action');
-      const __actionFn = (actionName && route.actions && Object.hasOwn(route.actions, actionName) ? route.actions[actionName] : null)
-        || (actionName && __layoutActions && Object.hasOwn(__layoutActions, actionName) ? __layoutActions[actionName] : null);
-      if (actionName && __actionFn) {
-        // Check if this is a fetch-based action call (onclick) with JSON args
-        const argsStr = formData.get('_args');
-        const isFetchAction = argsStr !== null;
+
+      // RPC call: GET ?_rpc=fnName&_args=[...] -> JSON response
+      const __rpcName = url.searchParams.get('_rpc');
+      if (request.method === 'GET' && __rpcName && route.rpc && Object.hasOwn(route.rpc, __rpcName)) {
+        if (request.headers.get('x-kuratchi-rpc') !== '1') {
+          return __secHeaders(new Response(JSON.stringify({ ok: false, error: 'Forbidden' }), {
+            status: 403, headers: { 'content-type': 'application/json', 'cache-control': 'no-store' }
+          }));
+        }
         try {
-          if (isFetchAction) {
-            const __parsed = JSON.parse(argsStr);
-            const args = Array.isArray(__parsed) ? __parsed : [];
-            await __actionFn(...args);
-          } else {
-            await __actionFn(formData);
+          const __rpcArgsStr = url.searchParams.get('_args');
+          let __rpcArgs = [];
+          if (__rpcArgsStr) {
+            const __parsed = JSON.parse(__rpcArgsStr);
+            __rpcArgs = Array.isArray(__parsed) ? __parsed : [];
           }
+          const __rpcResult = await route.rpc[__rpcName](...__rpcArgs);
+          return __secHeaders(new Response(JSON.stringify({ ok: true, data: __rpcResult }), {
+            headers: { 'content-type': 'application/json', 'cache-control': 'no-store' }
+          }));
         } catch (err) {
-          console.error('[kuratchi] Action error:', err);
+          console.error('[kuratchi] RPC error:', err);
+          const __errMsg = typeof __kuratchi_DEV__ !== 'undefined' ? err.message : 'Internal Server Error';
+          return __secHeaders(new Response(JSON.stringify({ ok: false, error: __errMsg }), {
+            status: 500, headers: { 'content-type': 'application/json', 'cache-control': 'no-store' }
+          }));
+        }
+      }
+
+      // Form action: POST with hidden _action field in form body
+      if (request.method === 'POST') {
+        if (!__isSameOrigin(request, url)) {
+          return __secHeaders(new Response('Forbidden', { status: 403 }));
+        }
+        const formData = await request.formData();
+        const actionName = formData.get('_action');
+        const __actionFn = (actionName && route.actions && Object.hasOwn(route.actions, actionName) ? route.actions[actionName] : null)
+          || (actionName && __layoutActions && Object.hasOwn(__layoutActions, actionName) ? __layoutActions[actionName] : null);
+        if (actionName && __actionFn) {
+          // Check if this is a fetch-based action call (onclick) with JSON args
+          const argsStr = formData.get('_args');
+          const isFetchAction = argsStr !== null;
+          try {
+            if (isFetchAction) {
+              const __parsed = JSON.parse(argsStr);
+              const args = Array.isArray(__parsed) ? __parsed : [];
+              await __actionFn(...args);
+            } else {
+              await __actionFn(formData);
+            }
+          } catch (err) {
+            console.error('[kuratchi] Action error:', err);
+            if (isFetchAction) {
+              const __errMsg = typeof __kuratchi_DEV__ !== 'undefined' ? err.message : 'Internal Server Error';
+              return __secHeaders(new Response(JSON.stringify({ ok: false, error: __errMsg }), {
+                status: 500, headers: { 'content-type': 'application/json' }
+              }));
+            }
+            const __loaded = route.load ? await route.load(match.params) : {};
+            const data = (__loaded && typeof __loaded === 'object') ? __loaded : { value: __loaded };
+            data.params = match.params;
+            data.breadcrumbs = __getLocals().__breadcrumbs ?? [];
+            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)
           if (isFetchAction) {
-            const __errMsg = typeof __kuratchi_DEV__ !== 'undefined' ? err.message : 'Internal Server Error';
-            return __secHeaders(new Response(JSON.stringify({ ok: false, error: __errMsg }), {
-              status: 500, headers: { 'content-type': 'application/json' }
+            return __attachCookies(new Response(JSON.stringify({ ok: true }), {
+              headers: { 'content-type': 'application/json' }
             }));
           }
-          const __loaded = route.load ? await route.load(match.params) : {};
-          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';
-          return ${opts.isLayoutAsync ? 'await ' : ''}__render(route, data);
-        }
-        // Fetch-based actions return lightweight JSON (no page re-render)
-        if (isFetchAction) {
-          return __attachCookies(new Response(JSON.stringify({ ok: true }), {
-            headers: { 'content-type': 'application/json' }
-          }));
+          // POST-Redirect-GET: redirect to custom target or back to same URL
+          const __locals = __getLocals();
+          const redirectTo = __locals.__redirectTo || url.pathname;
+          const redirectStatus = Number(__locals.__redirectStatus) || 303;
+          return __attachCookies(new Response(null, { status: redirectStatus, headers: { 'location': redirectTo } }));
         }
-        // POST-Redirect-GET: redirect to custom target or back to same URL
-        const __locals = __getLocals();
-        const redirectTo = __locals.__redirectTo || url.pathname;
-        const redirectStatus = Number(__locals.__redirectStatus) || 303;
-        return __attachCookies(new Response(null, { status: redirectStatus, headers: { 'location': redirectTo } }));
       }
-    }
 
-    // GET (or unmatched POST): load + render
+      // GET (or unmatched POST): load + render
+      try {
+        const __loaded = route.load ? await route.load(match.params) : {};
+        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 __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' } }));
+      }
+    };
+
     try {
-      const __loaded = route.load ? await route.load(match.params) : {};
-      const data = (__loaded && typeof __loaded === 'object') ? __loaded : { value: __loaded };
-      data.params = match.params;
-      data.breadcrumbs = __getLocals().__breadcrumbs ?? [];
-      return ${opts.isLayoutAsync ? 'await ' : ''}__render(route, data);
+      const __requestResponse = await __runRuntimeRequest(__runtimeCtx, async () => {
+        return __runRuntimeRoute(__runtimeCtx, __coreFetch);
+      });
+      return await __runRuntimeResponse(__runtimeCtx, __requestResponse);
     } 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 __handled = await __runRuntimeError(__runtimeCtx, err);
+      if (__handled) return __secHeaders(__handled);
+      throw err;
     }
   }
 }
 `;
 }
+function resolveRuntimeImportPath(projectDir) {
+    const candidates = [
+        { file: 'src/kuratchi.runtime.ts', importPath: '../src/kuratchi.runtime' },
+        { file: 'src/kuratchi.runtime.js', importPath: '../src/kuratchi.runtime' },
+        { file: 'src/kuratchi.runtime.mjs', importPath: '../src/kuratchi.runtime' },
+        { file: 'kuratchi.runtime.ts', importPath: '../kuratchi.runtime' },
+        { file: 'kuratchi.runtime.js', importPath: '../kuratchi.runtime' },
+        { file: 'kuratchi.runtime.mjs', importPath: '../kuratchi.runtime' },
+    ];
+    for (const candidate of candidates) {
+        if (fs.existsSync(path.join(projectDir, candidate.file))) {
+            return candidate.importPath;
+        }
+    }
+    return null;
+}
+function toWorkerImportPath(projectDir, outDir, filePath) {
+    const absPath = path.isAbsolute(filePath) ? filePath : path.join(projectDir, filePath);
+    let rel = path.relative(outDir, absPath).replace(/\\/g, '/');
+    if (!rel.startsWith('.'))
+        rel = `./${rel}`;
+    return rel.replace(/\.(ts|js|mjs|cjs)$/, '');
+}