@kuratchi/js 0.0.8 → 0.0.9

package/README.md

@@ -46,6 +46,18 @@ src/routes/blog/[slug]/page.html → /blog/:slug
 src/routes/layout.html        → shared layout wrapping all routes
 ```
 
+### Execution model
+
+Kuratchi routes are server-first.
+
+- `src/routes` defines server-rendered route modules.
+- Top-level route `<script>` blocks run on the server.
+- Template expressions, `if`, and `for` blocks render on the server.
+- `src/server` is for private server-only modules and reusable backend logic.
+- Reactive `$:` code is the browser-only escape hatch.
+
+Route files are not client files. They are server-rendered routes that can opt into small browser-side reactive behavior when needed.
+
 ### Route file structure
 
 ```html
@@ -64,6 +76,7 @@ src/routes/layout.html        → shared layout wrapping all routes
 ```
 
 The `$database/` alias resolves to `src/database/`. You can use any path alias configured in your tsconfig.
+Private server logic should live in `src/server/` and be imported into routes explicitly.
 
 ### Layout file
 
@@ -161,9 +174,11 @@ Block form is also supported:
 ```
 
 Notes:
-- This reactivity runs in browser scripts rendered in the template markup, not in the top server route `<script>` load/action block.
+- Route files are server-rendered by default. `$:` is the only browser-side execution primitive in a route template.
+- This reactivity runs in browser scripts rendered in the template markup, not in the top server route `<script>` block.
 - Object/array `let` bindings are proxy-backed automatically when `$:` is used.
 - `$: 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.
 
 ## Form actions
 
@@ -360,6 +375,7 @@ For Durable Objects, RPC is file-driven and automatic.
 - Put handler logic in a `.do.ts` file.
 - Exported functions in that file become RPC methods.
 - Import RPC methods from `$durable-objects/<file-name-without-.do>`.
+- RPC methods are still server-side code. They are exposed intentionally by the framework runtime, not because route files are client-side.
 
 ```html
 <script>
@@ -497,6 +513,24 @@ import { env } from 'cloudflare:workers';
 const result = await env.DB.prepare('SELECT 1').run();
 ```
 
+## Framework environment
+
+Kuratchi also exposes a framework build-mode flag:
+
+```html
+<script>
+  import { dev } from '@kuratchi/js/environment';
+  import { env } from 'cloudflare:workers';
+
+  const turnstileSiteKey = dev ? '' : (env.TURNSTILE_SITE_KEY || '');
+</script>
+```
+
+- `dev` is `true` for Kuratchi development builds
+- `dev` is `false` for production builds
+- `dev` is compile-time framework state, not a generic process env var
+- `@kuratchi/js/environment` is intended for server route code, not client `$:` scripts
+
 ## `kuratchi.config.ts`
 
 Optional. Required only when using framework integrations or Durable Objects.

package/dist/compiler/index.js

@@ -52,6 +52,11 @@ function rewriteWorkerEnvAliases(source, aliases) {
     }
     return out;
 }
+function buildDevAliasDeclarations(aliases, isDev) {
+    if (!aliases || aliases.length === 0)
+        return '';
+    return aliases.map((alias) => `const ${alias} = ${isDev ? 'true' : 'false'};`).join('\n');
+}
 function parseNamedImportBindings(line) {
     const namesMatch = line.match(/import\s*\{([^}]+)\}/);
     if (!namesMatch)
@@ -141,9 +146,13 @@ export function compile(options) {
                 .replace(/^\s*import[\s\S]*?from\s+['"][^'"]+['"]\s*;?/gm, '')
                 .trim()
             : '';
+        const devDecls = buildDevAliasDeclarations(compParsed.devAliases, !!options.isDev);
+        const effectivePropsCode = [devDecls, propsCode].filter(Boolean).join('\n');
         const transpiledPropsCode = propsCode
-            ? transpileTypeScript(propsCode, `component-script:${fileName}.ts`)
-            : '';
+            ? transpileTypeScript(effectivePropsCode, `component-script:${fileName}.ts`)
+            : devDecls
+                ? transpileTypeScript(devDecls, `component-script:${fileName}.ts`)
+                : '';
         // template source (parseFile already removes the <script> block)
         let source = compParsed.template;
         // Extract optional <style> block â€" CSS is scoped and injected once per route at compile time
@@ -651,6 +660,8 @@ export function compile(options) {
             }
             // Build the layout script body (data vars, etc.)
             let layoutScriptBody = layoutParsed.script.replace(/^\s*import[\s\S]*?from\s+['"][^'"]+['"]\s*;?/gm, '').trim();
+            const layoutDevDecls = buildDevAliasDeclarations(layoutParsed.devAliases, !!options.isDev);
+            layoutScriptBody = [layoutDevDecls, layoutScriptBody].filter(Boolean).join('\n');
             compiledLayout = `function __layout(__content) {
   const __esc = (v) => { if (v == null) return ''; return String(v).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;'); };
   ${layoutScriptBody ? layoutScriptBody + '\n  ' : ''}${finalLayoutBody}
@@ -1068,6 +1079,7 @@ export function compile(options) {
             index: i,
             pattern,
             renderBody,
+            isDev: !!options.isDev,
             parsed,
             fnToModule,
             rpcNameMap,
@@ -1373,7 +1385,7 @@ function discoverRoutes(routesDir) {
     return results;
 }
 function buildRouteObject(opts) {
-    const { pattern, renderBody, parsed, fnToModule, rpcNameMap, componentStyles } = opts;
+    const { pattern, renderBody, isDev, parsed, fnToModule, rpcNameMap, componentStyles } = opts;
     const hasFns = Object.keys(fnToModule).length > 0;
     const parts = [];
     parts.push(`    pattern: '${pattern}'`);
@@ -1381,12 +1393,15 @@ function buildRouteObject(opts) {
     let scriptBody = parsed.script
         ? parsed.script.replace(/^\s*import[\s\S]*?from\s+['"][^'"]+['"]\s*;?/gm, '').trim()
         : '';
+    const routeDevDecls = buildDevAliasDeclarations(parsed.devAliases, isDev);
+    scriptBody = [routeDevDecls, scriptBody].filter(Boolean).join('\n');
     scriptBody = rewriteImportedFunctionCalls(scriptBody, fnToModule);
     scriptBody = rewriteWorkerEnvAliases(scriptBody, parsed.workerEnvAliases);
     let explicitLoadFunction = parsed.loadFunction
         ? parsed.loadFunction.replace(/^export\s+/, '').trim()
         : '';
     if (explicitLoadFunction) {
+        explicitLoadFunction = [routeDevDecls, explicitLoadFunction].filter(Boolean).join('\n');
         explicitLoadFunction = rewriteImportedFunctionCalls(explicitLoadFunction, fnToModule);
         explicitLoadFunction = rewriteWorkerEnvAliases(explicitLoadFunction, parsed.workerEnvAliases);
     }

package/dist/compiler/parser.d.ts

@@ -40,6 +40,8 @@ export interface ParsedFile {
     loadReturnVars: string[];
     /** Local aliases for Cloudflare Workers env imported from cloudflare:workers */
     workerEnvAliases: string[];
+    /** Local aliases for dev imported from @kuratchi/js/environment */
+    devAliases: string[];
 }
 interface ParseFileOptions {
     kind?: 'route' | 'layout' | 'component';

package/dist/compiler/parser.js

@@ -158,6 +158,26 @@ function extractCloudflareEnvAliases(importLine) {
     }
     return aliases;
 }
+function extractKuratchiEnvironmentDevAliases(importLine) {
+    if (!/from\s+['"]@kuratchi\/js\/environment['"]/.test(importLine))
+        return [];
+    const namedMatch = importLine.match(/import\s*\{([\s\S]*?)\}\s*from\s+['"]@kuratchi\/js\/environment['"]/);
+    if (!namedMatch) {
+        throw new Error('[kuratchi compiler] @kuratchi/js/environment only supports named imports.');
+    }
+    const aliases = [];
+    for (const rawPart of splitTopLevel(namedMatch[1], ',')) {
+        const part = rawPart.trim();
+        if (!part)
+            continue;
+        const devMatch = part.match(/^dev(?:\s+as\s+([A-Za-z_$][\w$]*))?$/);
+        if (!devMatch) {
+            throw new Error('[kuratchi compiler] @kuratchi/js/environment currently only exports `dev`.');
+        }
+        aliases.push(devMatch[1] || 'dev');
+    }
+    return aliases;
+}
 function extractReturnObjectKeys(body) {
     const keys = [];
     let i = 0;
@@ -648,6 +668,7 @@ export function parseFile(source, options = {}) {
     const clientImports = [];
     const componentImports = {};
     const workerEnvAliases = [];
+    const devAliases = [];
     if (script) {
         // Support both single-line and multiline static imports.
         const importRegex = /^\s*import[\s\S]*?from\s+['"][^'"]+['"]\s*;?/gm;
@@ -669,6 +690,14 @@ export function parseFile(source, options = {}) {
                 componentImports[componentName] = `${pkg}:${fileName}`; // e.g. "@kuratchi/ui:badge"
             }
             else {
+                const devImportAliases = extractKuratchiEnvironmentDevAliases(line);
+                if (devImportAliases.length > 0) {
+                    for (const alias of devImportAliases) {
+                        if (!devAliases.includes(alias))
+                            devAliases.push(alias);
+                    }
+                    continue;
+                }
                 serverImports.push(line);
             }
             for (const alias of extractCloudflareEnvAliases(line)) {
@@ -683,6 +712,9 @@ export function parseFile(source, options = {}) {
         while ((m = importRegex.exec(clientScript)) !== null) {
             const line = m[0].trim();
             clientImports.push(line);
+            if (extractKuratchiEnvironmentDevAliases(line).length > 0) {
+                throw new Error(`[kuratchi compiler] ${options.filePath || kind}\nClient <script> blocks cannot import from @kuratchi/js/environment.\nUse route server script code and pass values into the template explicitly.`);
+            }
             if (extractCloudflareEnvAliases(line).length > 0) {
                 throw buildEnvAccessError(kind, options.filePath, 'Client <script> blocks cannot import env from cloudflare:workers.');
             }
@@ -813,6 +845,7 @@ export function parseFile(source, options = {}) {
         clientImports,
         loadReturnVars,
         workerEnvAliases,
+        devAliases,
     };
 }
 import { transpileTypeScript } from './transpile.js';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@kuratchi/js",
-    "version": "0.0.8",
+    "version": "0.0.9",
     "description": "A thin, Cloudflare Workers-native web framework with Svelte-inspired syntax",
     "type": "module",
     "main": "./dist/index.js",
@@ -36,6 +36,10 @@
             "types": "./dist/compiler/index.d.ts",
             "import": "./dist/compiler/index.js"
         },
+        "./environment": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
         "./package.json": "./package.json"
     },
     "engines": {