@kuratchi/js 0.0.19 → 0.0.21

package/README.md

@@ -183,6 +183,60 @@ Notes:
 - `$: name = expr` works; when replacing proxy-backed values, the compiler preserves reactivity under the hood.
 - You should not need `if (browser)` style guards in normal Kuratchi route code. If browser checks become necessary outside `$:`, the boundary is likely in the wrong place.
 
+### `$client` server calls
+
+Use `$client/*` for browser orchestration, then import server functions from `$server/*` inside that client module. Kuratchi generates a route-scoped browser RPC proxy automatically.
+
+```ts
+// src/client/migration.ts
+import { testMigrationConnection } from '$server/incus';
+
+export async function testConnection(sourceIp: string) {
+  const result = await testMigrationConnection(sourceIp);
+  console.log(result.success, result.message);
+}
+```
+
+```html
+<script>
+  import { testConnection } from '$client/migration';
+</script>
+
+<button onclick={testConnection(sourceIp)}>Test Connection</button>
+```
+
+Behavior:
+- Kuratchi only ships the `$client` module to the browser.
+- Any `$server` imports used inside that `$client` graph become generated fetch proxies for the current route.
+- Your client handler can `await` them directly from `onclick={fn(args)}` or from browser-side `$:` blocks.
+
+Failure and edge behavior:
+- Named and default `$server` imports are supported inside `$client` / `$shared` browser graphs.
+- Namespace imports like `import * as api from '$server/foo'` are currently rejected in browser code.
+- Remote call failures reject with the server error message when available, otherwise `HTTP <status>`.
+
+### Awaited remote reads
+
+For renderable remote reads, use direct `await fn(args)` markup. Kuratchi lowers it to a route query, renders it on the server, and refreshes it after successful `$client` remote calls.
+
+```html
+<script>
+  import { getMigrationConnectionStatus } from '$server/incus';
+</script>
+
+<p>{await getMigrationConnectionStatus(sourceIp)}</p>
+```
+
+Behavior:
+- The read runs during the initial server render.
+- Kuratchi emits refresh metadata so the same block can be re-fetched without a full page reload.
+- Successful `$client` remote calls automatically invalidate awaited reads on the current page.
+
+Failure and edge behavior:
+- The supported syntax is direct markup form: `{await fn(args)}`.
+- Awaited reads are intended for values that render cleanly to text/HTML output.
+- Complex promise expressions or chained property access should be wrapped in a dedicated server helper that returns the render-ready value.
+
 ## Form actions
 
 Export server functions from a route's `<script>` block and reference them with `action={fn}`. The compiler automatically registers them as dispatchable actions.
@@ -278,6 +332,8 @@ Throw `PageError` from a route's load scope to return the correct HTTP error pag
 import { PageError } from '@kuratchi/js';
 
 // In src/routes/posts/[id]/index.html <script> block:
+import { params } from '@kuratchi/js/request';
+
 const post = await db.posts.findOne({ id: params.id });
 if (!post) throw new PageError(404);
 if (!post.isPublished && !currentUser?.isAdmin) throw new PageError(403);
@@ -341,14 +397,33 @@ After a `data-action` call succeeds, elements with `data-refresh` re-fetch their
 </section>
 ```
 
-### `data-get` — client-side navigation
+### `data-get` — query blocks and refreshable reads
 
-Navigate to a URL on click (respects `http:`/`https:` only):
+Use `data-get={fn(args)}` with `data-as` to bind a server read into a fragment that Kuratchi can refresh:
 
 ```html
-<div data-get="/items/{item.id}">Click to navigate</div>
+<section data-get={getItems(projectId)} data-as="items">
+  if (items.loading) {
+    <p>Loading…</p>
+  } else if (items.error) {
+    <p>{items.error}</p>
+  } else {
+    for (const item of (items.data ?? [])) {
+      <article>{item.title}</article>
+    }
+  }
+</section>
 ```
 
+Behavior:
+- The server read runs on the initial render.
+- Kuratchi stores fragment metadata so the block can be refreshed by `data-refresh`, polling, or invalidation.
+- Query state follows `{ loading, error, success, empty, data, state }`.
+
+Failure and edge behavior:
+- `data-as` is required for query-state blocks.
+- `data-get="/path"` still works as click-to-navigate when used as a plain string URL on an element without query state metadata.
+
 ### `data-poll` — polling
 
 Poll and update an element's content at a human-readable interval with automatic exponential backoff:
@@ -408,6 +483,91 @@ For Durable Objects, RPC is file-driven and automatic.
   <button type="submit">Create</button>
 </form>
 ```
+
+### RPC Validation Without Dependencies
+
+Kuratchi ships a small built-in schema API for route RPCs and Durable Object RPC methods, so you do not need `zod`, `valibot`, or any other runtime dependency just to validate client-callable input.
+
+Declare schemas in a companion `schemas` object. Keys must match the public RPC function or method names:
+
+```ts
+import { schema, type InferSchema } from '@kuratchi/js';
+
+export const schemas = {
+  createSite: schema({
+    name: schema.string().min(1),
+    slug: schema.string().min(1),
+    publish: schema.boolean().optional(false),
+  }),
+};
+
+export async function createSite(data: InferSchema<typeof schemas.createSite>) {
+  return { id: `${data.slug}-1`, publish: data.publish };
+}
+```
+
+This works for normal exported route RPC functions without changing the function declaration style. The schema lives alongside the function instead of wrapping it.
+
+Durable Object classes use the same convention via `static schemas`:
+
+```ts
+import { DurableObject } from 'cloudflare:workers';
+import { schema, type InferSchema } from '@kuratchi/js';
+
+export default class SitesDO extends DurableObject {
+  static schemas = {
+    saveDraft: schema({
+      title: schema.string().min(1),
+      content: schema.string().min(1),
+    }),
+  };
+
+  async saveDraft(data: InferSchema<(typeof SitesDO.schemas).saveDraft>) {
+    return { ok: true, slug: data.title.toLowerCase().replace(/ /g, '-') };
+  },
+}
+```
+
+If the payload does not match the schema, Kuratchi returns `400` with a validation error instead of executing the RPC. Schema-backed RPCs accept a single object argument.
+
+Rules:
+- Route RPC modules use `export const schemas = { ... }`.
+- Durable Object classes use `static schemas = { ... }`.
+- Schema keys must match public function or method names exactly.
+- Schema-backed RPC entrypoints take one object argument.
+- Today, the typed handler pattern is `InferSchema<typeof schemas.name>` or `InferSchema<(typeof MyDO.schemas).methodName>`.
+
+Available schema builders:
+- `schema({ ... })`
+- `schema.string()`
+- `schema.number()`
+- `schema.boolean()`
+- `schema.file()`
+- `.optional(defaultValue)`
+- `.list()`
+- `.min(value)`
+
+Example with nested objects, arrays, and defaults:
+
+```ts
+import { schema, type InferSchema } from '@kuratchi/js';
+
+export const schemas = {
+  createProfile: schema({
+    name: schema.string().min(1),
+    info: schema({
+      height: schema.number(),
+      likesDogs: schema.boolean().optional(false),
+    }),
+    attributes: schema.string().list(),
+  }),
+};
+
+export async function createProfile(data: InferSchema<typeof schemas.createProfile>) {
+  return { ok: true, profile: data };
+}
+```
+
 ## Durable Objects
 
 Durable Object behavior is enabled by filename suffix.
@@ -671,24 +831,50 @@ import {
 } from '@kuratchi/js';
 ```
 
+### Virtual Modules
+
+Kuratchi provides virtual modules for request-scoped state. Use these in route files:
+
+| Virtual Module | Description |
+|----------------|-------------|
+| `kuratchi:request` | Request state: `url`, `params`, `searchParams`, `headers`, `locals`, etc. |
+| `kuratchi:navigation` | Server-side redirect helper |
+
 ### Request helpers
 
-For a batteries-included request layer, import pre-parsed request state from `@kuratchi/js/request`:
+For a batteries-included request layer, import pre-parsed request state from `kuratchi:request`:
 
 ```ts
-import { url, pathname, searchParams, slug } from '@kuratchi/js/request';
+import { url, pathname, searchParams, params, slug, locals } from 'kuratchi:request';
 
 const page = pathname;
 const tab = searchParams.get('tab');
+const postId = params.id;
 const postSlug = slug;
 ```
 
 - `url` is the parsed `URL` for the current request.
 - `pathname` is the full path, like `/blog/hello-world`.
 - `searchParams` is `url.searchParams` for the current request.
+- `params` is the matched route params object, like `{ slug: 'hello-world' }`.
 - `slug` is `params.slug` when the matched route defines a `slug` param.
-- `headers`, `method`, and `params` are also exported from `@kuratchi/js/request`.
-- Use `getRequest()` when you want the raw native `Request` object.
+- `headers` and `method` are also exported from `kuratchi:request`.
+- `locals` is the request-scoped locals object (typed via `App.Locals` in `app.d.ts`).
+- Use `getRequest()` from `@kuratchi/js` when you want the raw native `Request` object.
+
+### Server-side redirect
+
+Import `redirect` from `kuratchi:navigation` for server-side redirects:
+
+```ts
+import { redirect } from 'kuratchi:navigation';
+
+// Redirect to another page (throws RedirectError, caught by framework)
+redirect('/dashboard');
+redirect('/login', 302);
+```
+
+`redirect()` works in route scripts, `$server/` modules, and form actions. It throws a `RedirectError` that the framework catches and converts to a proper HTTP redirect response (default 303 for POST-Redirect-GET).
 
 ## Runtime Hook
 

package/dist/cli.js

@@ -29,6 +29,9 @@ async function main() {
         case 'create':
             await runCreate();
             return;
+        case 'types':
+            await runTypes();
+            return;
         default:
             console.log(`
 KuratchiJS CLI
@@ -38,6 +41,7 @@ Usage:
   kuratchi build          Compile routes once
   kuratchi dev            Compile, watch for changes, and start wrangler dev server
   kuratchi watch          Compile + watch only (no wrangler — for custom setups)
+  kuratchi types          Generate TypeScript types from schema to src/app.d.ts
 `);
             process.exit(1);
     }
@@ -49,6 +53,10 @@ async function runCreate() {
     const positional = remaining.filter(a => !a.startsWith('-'));
     await create(positional[0], flags);
 }
+async function runTypes() {
+    const { writeAppTypes } = await import('./compiler/type-generator.js');
+    writeAppTypes({ projectDir });
+}
 async function runBuild(isDev = false) {
     console.log('[kuratchi] Compiling...');
     try {

package/dist/compiler/client-module-pipeline.d.ts

@@ -5,6 +5,13 @@ export interface ClientEventRegistration {
     handlerId: string;
     argsExpr: string | null;
 }
+export interface ClientServerProxyBinding {
+    sourceKey: string;
+    moduleSpecifier: string;
+    importerDir: string;
+    importedName: string;
+    rpcId: string;
+}
 export interface ClientModuleCompiler {
     createRegistry(scopeId: string, importEntries: RouteImportEntry[]): ClientRouteRegistry;
     createRouteRegistry(routeIndex: number, importEntries: RouteImportEntry[]): ClientRouteRegistry;
@@ -14,6 +21,7 @@ export interface ClientRouteRegistry {
     hasBindings(): boolean;
     hasBindingReference(expression: string): boolean;
     registerEventHandler(eventName: string, expression: string): ClientEventRegistration | null;
+    getServerProxyBindings(): ClientServerProxyBinding[];
     buildEntryAsset(): {
         assetName: string;
         asset: CompiledAsset;

package/dist/compiler/client-module-pipeline.js

@@ -1,6 +1,7 @@
 import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import ts from 'typescript';
 import { collectReferencedIdentifiers, parseImportStatement } from './import-linking.js';
 function resolveExistingModuleFile(absBase) {
     const candidates = [
@@ -20,6 +21,19 @@ function resolveExistingModuleFile(absBase) {
     }
     return null;
 }
+function normalizePath(value) {
+    return value.replace(/\\/g, '/');
+}
+function isWithinDir(target, dir) {
+    const relative = path.relative(dir, target);
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+function getTopLevelImportLines(source) {
+    const sourceFile = ts.createSourceFile('kuratchi-client-module.ts', source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    return sourceFile.statements
+        .filter(ts.isImportDeclaration)
+        .map((statement) => statement.getText(sourceFile).trim());
+}
 function buildAsset(name, content) {
     return {
         name,
@@ -44,19 +58,24 @@ function rewriteImportSpecifiers(source, rewriteSpecifier) {
     return rewritten;
 }
 function resolveClientImportTarget(srcDir, importerAbs, spec) {
+    const serverDir = path.join(srcDir, 'server');
     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 !== 'client' && folder !== 'shared') {
-            throw new Error(`[kuratchi compiler] Unsupported browser import realm "${spec}". Only $client/* and $shared/* may be loaded in the browser.`);
+        if (folder !== 'client' && folder !== 'shared' && folder !== 'server') {
+            throw new Error(`[kuratchi compiler] Unsupported browser import realm "${spec}". Only $client/*, $shared/*, and $server/* may be referenced from browser code.`);
         }
         const abs = path.join(srcDir, folder, rest);
         const resolved = resolveExistingModuleFile(abs);
         if (!resolved) {
             throw new Error(`[kuratchi compiler] Browser import not found: ${spec}`);
         }
-        return resolved;
+        return {
+            kind: folder === 'server' ? 'server' : 'browser',
+            resolved,
+            moduleSpecifier: spec,
+        };
     }
     if (spec.startsWith('.')) {
         const abs = path.resolve(path.dirname(importerAbs), spec);
@@ -64,15 +83,28 @@ function resolveClientImportTarget(srcDir, importerAbs, spec) {
         if (!resolved) {
             throw new Error(`[kuratchi compiler] Browser import not found: ${spec}`);
         }
-        return resolved;
+        return {
+            kind: isWithinDir(resolved, serverDir) ? 'server' : 'browser',
+            resolved,
+            moduleSpecifier: spec,
+        };
     }
-    throw new Error(`[kuratchi compiler] Browser modules currently only support project-local imports ($client, $shared, or relative). Unsupported import: ${spec}`);
+    throw new Error(`[kuratchi compiler] Browser modules currently only support project-local imports ($client, $shared, $server, or relative). Unsupported import: ${spec}`);
+}
+function buildServerProxyRpcId(sourceKey, importedName) {
+    const hash = crypto.createHash('sha1').update(`${sourceKey}:${importedName}`).digest('hex').slice(0, 12);
+    return `rpc_remote_${hash}`;
 }
 class CompilerBackedClientRouteRegistry {
     compiler;
     bindingMap = new Map();
     clientOnlyBindings = new Set();
     handlerByKey = new Map();
+    routeModuleAssets = new Map();
+    serverProxyBindings = new Map();
+    serverProxyAssets = new Map();
+    scannedBrowserModules = new Set();
+    prepared = false;
     routeId;
     constructor(compiler, scopeId, importEntries) {
         this.compiler = compiler;
@@ -149,9 +181,14 @@ class CompilerBackedClientRouteRegistry {
             argsExpr: parsed.argsExpr,
         };
     }
+    getServerProxyBindings() {
+        this.prepareClientGraph();
+        return Array.from(this.serverProxyBindings.values());
+    }
     buildEntryAsset() {
         if (this.handlerByKey.size === 0)
             return null;
+        this.prepareClientGraph();
         const usedImportLines = new Map();
         for (const record of this.handlerByKey.values()) {
             const binding = this.bindingMap.get(record.rootBinding);
@@ -170,8 +207,11 @@ class CompilerBackedClientRouteRegistry {
             const parsed = parseImportStatement(entry.line);
             if (!parsed.moduleSpecifier)
                 continue;
-            const targetAbs = resolveClientImportTarget(this.compiler.srcDir, path.join(entry.importerDir, '__route__.ts'), parsed.moduleSpecifier);
-            const targetAssetName = this.compiler.transformClientModule(targetAbs);
+            const target = resolveClientImportTarget(this.compiler.srcDir, path.join(entry.importerDir, '__route__.ts'), parsed.moduleSpecifier);
+            if (target.kind !== 'browser') {
+                throw new Error(`[kuratchi compiler] Top-level route browser imports cannot reference server modules directly: ${parsed.moduleSpecifier}`);
+            }
+            const targetAssetName = this.transformRouteClientModule(target.resolved);
             const relSpecifier = toRelativeSpecifier(assetName, targetAssetName);
             importLines.push(entry.line.replace(parsed.moduleSpecifier, relSpecifier));
         }
@@ -189,6 +229,140 @@ class CompilerBackedClientRouteRegistry {
         this.compiler.registerAsset(asset);
         return { assetName, asset };
     }
+    prepareClientGraph() {
+        if (this.prepared)
+            return;
+        this.prepared = true;
+        const usedImportLines = new Map();
+        for (const record of this.handlerByKey.values()) {
+            const binding = this.bindingMap.get(record.rootBinding);
+            if (!binding)
+                continue;
+            if (!usedImportLines.has(binding.importLine)) {
+                usedImportLines.set(binding.importLine, {
+                    line: binding.importLine,
+                    importerDir: binding.importerDir,
+                });
+            }
+        }
+        for (const entry of usedImportLines.values()) {
+            const parsed = parseImportStatement(entry.line);
+            if (!parsed.moduleSpecifier)
+                continue;
+            const target = resolveClientImportTarget(this.compiler.srcDir, path.join(entry.importerDir, '__route__.ts'), parsed.moduleSpecifier);
+            if (target.kind === 'browser') {
+                this.scanBrowserModule(target.resolved);
+            }
+        }
+        for (const binding of this.serverProxyBindings.values()) {
+            this.ensureServerProxyAsset(binding.sourceKey);
+        }
+    }
+    scanBrowserModule(entryAbsPath) {
+        const resolved = resolveExistingModuleFile(entryAbsPath) ?? entryAbsPath;
+        const normalized = normalizePath(resolved);
+        if (this.scannedBrowserModules.has(normalized))
+            return;
+        this.scannedBrowserModules.add(normalized);
+        if (!fs.existsSync(resolved)) {
+            throw new Error(`[kuratchi compiler] Browser module not found: ${resolved}`);
+        }
+        const source = fs.readFileSync(resolved, 'utf-8');
+        for (const importLine of getTopLevelImportLines(source)) {
+            const parsed = parseImportStatement(importLine);
+            if (!parsed.moduleSpecifier)
+                continue;
+            const target = resolveClientImportTarget(this.compiler.srcDir, resolved, parsed.moduleSpecifier);
+            if (target.kind === 'browser') {
+                this.scanBrowserModule(target.resolved);
+                continue;
+            }
+            if (parsed.namespaceImport) {
+                throw new Error(`[kuratchi compiler] Browser code cannot use namespace imports from server modules: ${parsed.moduleSpecifier}. Use named imports instead.`);
+            }
+            for (const binding of parsed.bindings) {
+                const importedName = binding.imported;
+                const sourceKey = normalizePath(target.resolved);
+                const key = `${sourceKey}::${importedName}`;
+                if (!this.serverProxyBindings.has(key)) {
+                    this.serverProxyBindings.set(key, {
+                        sourceKey,
+                        moduleSpecifier: target.moduleSpecifier,
+                        importerDir: path.dirname(resolved),
+                        importedName,
+                        rpcId: buildServerProxyRpcId(sourceKey, importedName),
+                    });
+                }
+            }
+        }
+    }
+    ensureServerProxyAsset(sourceKey) {
+        const cached = this.serverProxyAssets.get(sourceKey);
+        if (cached)
+            return cached;
+        const relFromSrc = path.relative(this.compiler.srcDir, sourceKey).replace(/\\/g, '/');
+        const assetName = `__kuratchi/client/routes/${this.routeId}/server/${relFromSrc.replace(/\.(ts|js|mjs|cjs)$/i, '.js')}`;
+        const bindings = Array.from(this.serverProxyBindings.values())
+            .filter((binding) => binding.sourceKey === sourceKey)
+            .sort((a, b) => a.importedName.localeCompare(b.importedName));
+        const lines = [
+            `function __kuratchiGetCsrf(){`,
+            `  return (document.cookie.match(/(?:^|;\\s*)__kuratchi_csrf=([^;]*)/) || [])[1] || '';`,
+            `}`,
+            `async function __kuratchiCallRemote(rpcId, args){`,
+            `  const url = new URL(window.location.pathname, window.location.origin);`,
+            `  url.searchParams.set('_rpc', rpcId);`,
+            `  if (args.length > 0) url.searchParams.set('_args', JSON.stringify(args));`,
+            `  const headers = { 'x-kuratchi-rpc': '1' };`,
+            `  const csrfToken = __kuratchiGetCsrf();`,
+            `  if (csrfToken) headers['x-kuratchi-csrf'] = csrfToken;`,
+            `  const response = await fetch(url.toString(), { method: 'GET', headers });`,
+            `  const payload = await response.json().catch(() => ({ ok: false, error: 'Invalid RPC response' }));`,
+            `  if (!response.ok || !payload || payload.ok !== true) {`,
+            `    throw new Error((payload && payload.error) || ('HTTP ' + response.status));`,
+            `  }`,
+            `  window.dispatchEvent(new CustomEvent('kuratchi:invalidate-reads', { detail: { rpcId: rpcId } }));`,
+            `  return payload.data;`,
+            `}`,
+        ];
+        for (const binding of bindings) {
+            if (binding.importedName === 'default') {
+                lines.push(`export default async function(...args){ return __kuratchiCallRemote(${JSON.stringify(binding.rpcId)}, args); }`);
+            }
+            else {
+                lines.push(`export async function ${binding.importedName}(...args){ return __kuratchiCallRemote(${JSON.stringify(binding.rpcId)}, args); }`);
+            }
+        }
+        const asset = buildAsset(assetName, lines.join('\n'));
+        this.compiler.registerAsset(asset);
+        this.serverProxyAssets.set(sourceKey, assetName);
+        return assetName;
+    }
+    transformRouteClientModule(entryAbsPath) {
+        const resolved = resolveExistingModuleFile(entryAbsPath) ?? entryAbsPath;
+        const normalized = normalizePath(resolved);
+        const cached = this.routeModuleAssets.get(normalized);
+        if (cached)
+            return cached;
+        const relFromSrc = path.relative(this.compiler.srcDir, resolved).replace(/\\/g, '/');
+        const assetName = `__kuratchi/client/routes/${this.routeId}/modules/${relFromSrc.replace(/\.(ts|js|mjs|cjs)$/i, '.js')}`;
+        this.routeModuleAssets.set(normalized, assetName);
+        if (!fs.existsSync(resolved)) {
+            throw new Error(`[kuratchi compiler] Browser module not found: ${resolved}`);
+        }
+        const source = fs.readFileSync(resolved, 'utf-8');
+        const rewritten = rewriteImportSpecifiers(source, (spec) => {
+            const target = resolveClientImportTarget(this.compiler.srcDir, resolved, spec);
+            if (target.kind === 'browser') {
+                const targetAssetName = this.transformRouteClientModule(target.resolved);
+                return toRelativeSpecifier(assetName, targetAssetName);
+            }
+            const proxyAssetName = this.ensureServerProxyAsset(normalizePath(target.resolved));
+            return toRelativeSpecifier(assetName, proxyAssetName);
+        });
+        this.compiler.registerAsset(buildAsset(assetName, rewritten));
+        return assetName;
+    }
     parseClientExpression(expression) {
         const trimmed = expression.trim();
         if (!trimmed)
@@ -212,7 +386,6 @@ class CompilerBackedClientModuleCompiler {
     projectDir;
     srcDir;
     compiledAssets = new Map();
-    transformedModules = new Map();
     constructor(projectDir, srcDir) {
         this.projectDir = projectDir;
         this.srcDir = srcDir;
@@ -229,28 +402,6 @@ class CompilerBackedClientModuleCompiler {
     registerAsset(asset) {
         this.compiledAssets.set(asset.name, asset);
     }
-    transformClientModule(entryAbsPath) {
-        const resolved = resolveExistingModuleFile(entryAbsPath) ?? entryAbsPath;
-        const normalized = resolved.replace(/\\/g, '/');
-        const cached = this.transformedModules.get(normalized);
-        if (cached)
-            return cached;
-        const relFromSrc = path.relative(this.srcDir, resolved).replace(/\\/g, '/');
-        const assetName = `__kuratchi/client/modules/${relFromSrc.replace(/\.(ts|js|mjs|cjs)$/i, '.js')}`;
-        this.transformedModules.set(normalized, assetName);
-        if (!fs.existsSync(resolved)) {
-            throw new Error(`[kuratchi compiler] Browser module not found: ${resolved}`);
-        }
-        // TypeScript is preserved — wrangler's esbuild handles transpilation
-        const source = fs.readFileSync(resolved, 'utf-8');
-        let rewritten = rewriteImportSpecifiers(source, (spec) => {
-            const targetAbs = resolveClientImportTarget(this.srcDir, resolved, spec);
-            const targetAssetName = this.transformClientModule(targetAbs);
-            return toRelativeSpecifier(assetName, targetAssetName);
-        });
-        this.registerAsset(buildAsset(assetName, rewritten));
-        return assetName;
-    }
 }
 export function createClientModuleCompiler(opts) {
     return new CompilerBackedClientModuleCompiler(opts.projectDir, opts.srcDir);

package/dist/compiler/compiler-shared.d.ts

@@ -61,13 +61,36 @@ export interface DoClassMethodEntry {
     hasWorkerContextCalls: boolean;
     callsThisMethods: string[];
 }
+export interface DoClassContributorEntry {
+    /** Absolute path to the contributor source file */
+    absPath: string;
+    /** Exported class name */
+    className: string;
+    /** Whether the class is exported as named or default */
+    exportKind: 'named' | 'default';
+    /** Own methods declared on this contributor */
+    classMethods: DoClassMethodEntry[];
+    /** Inheritance depth from the base DO class (1 = direct child) */
+    depth: number;
+}
+export interface ExportedClassEntry {
+    className: string;
+    exportKind: 'named' | 'default';
+}
+export interface RelativeImportClassEntry {
+    source: string;
+    importedName: string | 'default';
+}
 export interface DoHandlerEntry {
     fileName: string;
     absPath: string;
     binding: string;
     mode: 'class' | 'function';
     className?: string;
+    exportKind?: 'named' | 'default';
     classMethods: DoClassMethodEntry[];
+    /** Additional exported classes in the same DO folder that extend this base DO class */
+    classContributors: DoClassContributorEntry[];
     exportedFunctions: string[];
 }
 export declare function toSafeIdentifier(input: string): string;

package/dist/compiler/component-pipeline.js

@@ -97,7 +97,15 @@ export function createComponentCompiler(options) {
         const scopeOpen = `__parts.push('<div class="${scopeHash}">');`;
         const scopeClose = `__parts.push('</div>');`;
         const bodyLines = body.split('\n');
-        const scopedBody = [bodyLines[0], scopeOpen, ...bodyLines.slice(1), scopeClose].join('\n');
+        const insertIndex = bodyLines.findIndex(l => l.startsWith('let __html'));
+        const safeInsertIndex = insertIndex === -1 ? bodyLines.length : insertIndex;
+        const scopedBody = [
+            bodyLines[0],
+            scopeOpen,
+            ...bodyLines.slice(1, safeInsertIndex),
+            scopeClose,
+            ...bodyLines.slice(safeInsertIndex)
+        ].join('\n');
         const fnBody = effectivePropsCode ? `${effectivePropsCode}\n  ${scopedBody}` : scopedBody;
         const compiled = `function ${funcName}(props, __esc) {\n  ${fnBody}\n  return __html;\n}`;
         compiledComponentCache.set(fileName, compiled);