@kuratchi/js 0.0.3 → 0.0.5

package/dist/compiler/parser.d.ts

@@ -1,13 +1,17 @@
 /**
  * HTML file parser.
  *
- * Extracts the top-level <script> block (before the HTML document).
+ * Extracts the top-level compile-time <script> block (before the HTML document).
+ * A top-level block containing reactive `$:` labels is preserved in template output
+ * as client script.
  * Everything else is the template — full HTML with native JS flow control.
  * <style> inside the HTML is NOT extracted; it's part of the template.
  */
 export interface ParsedFile {
-    /** Script content (the server-side code, minus imports) */
+    /** Script content (compile-time code, minus imports) */
     script: string | null;
+    /** Explicit server-side load function exported from the route script */
+    loadFunction: string | null;
     /** Template — the full HTML document with inline JS flow control */
     template: string;
     /** All imports from the script block */
@@ -30,11 +34,23 @@ export interface ParsedFile {
         key?: string;
         rpcId?: string;
     }>;
+    /** Imports found in a top-level client script block */
+    clientImports: string[];
+    /** Top-level names returned from explicit load() */
+    loadReturnVars: string[];
+    /** Local aliases for Cloudflare Workers env imported from cloudflare:workers */
+    workerEnvAliases: string[];
+}
+interface ParseFileOptions {
+    kind?: 'route' | 'layout' | 'component';
+    filePath?: string;
 }
 /**
  * Parse a .html route file.
  *
- * The <script> block at the top is extracted for the compiler.
+ * The top-level compile-time <script> block is extracted for the compiler.
+ * If it includes reactive `$:` labels, it is preserved in template output.
  * Everything else (the HTML document) becomes the template.
  */
-export declare function parseFile(source: string): ParsedFile;
+export declare function parseFile(source: string, options?: ParseFileOptions): ParsedFile;
+export {};

package/dist/compiler/parser.js

@@ -1,10 +1,15 @@
 /**
  * HTML file parser.
  *
- * Extracts the top-level <script> block (before the HTML document).
+ * Extracts the top-level compile-time <script> block (before the HTML document).
+ * A top-level block containing reactive `$:` labels is preserved in template output
+ * as client script.
  * Everything else is the template — full HTML with native JS flow control.
  * <style> inside the HTML is NOT extracted; it's part of the template.
  */
+function hasReactiveLabel(scriptBody) {
+    return /\$\s*:/.test(scriptBody);
+}
 function splitTopLevel(input, delimiter) {
     const parts = [];
     let start = 0;
@@ -103,6 +108,220 @@ function pushIdentifier(name, out) {
     if (!out.includes(name))
         out.push(name);
 }
+function findMatchingToken(input, openPos, openChar, closeChar) {
+    let depth = 0;
+    let quote = null;
+    let escaped = false;
+    for (let i = openPos; i < input.length; i++) {
+        const ch = input[i];
+        if (quote) {
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (ch === '\\') {
+                escaped = true;
+                continue;
+            }
+            if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === '`') {
+            quote = ch;
+            continue;
+        }
+        if (ch === openChar)
+            depth++;
+        else if (ch === closeChar) {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return -1;
+}
+function extractCloudflareEnvAliases(importLine) {
+    if (!/from\s+['"]cloudflare:workers['"]/.test(importLine))
+        return [];
+    const namedMatch = importLine.match(/import\s*\{([\s\S]*?)\}\s*from\s+['"]cloudflare:workers['"]/);
+    if (!namedMatch)
+        return [];
+    const aliases = [];
+    for (const rawPart of splitTopLevel(namedMatch[1], ',')) {
+        const part = rawPart.trim();
+        if (!part)
+            continue;
+        const envMatch = part.match(/^env(?:\s+as\s+([A-Za-z_$][\w$]*))?$/);
+        if (envMatch)
+            aliases.push(envMatch[1] || 'env');
+    }
+    return aliases;
+}
+function extractReturnObjectKeys(body) {
+    const keys = [];
+    let i = 0;
+    let depthParen = 0;
+    let depthBracket = 0;
+    let depthBrace = 0;
+    let quote = null;
+    let escaped = false;
+    while (i < body.length) {
+        const ch = body[i];
+        if (quote) {
+            if (escaped) {
+                escaped = false;
+                i++;
+                continue;
+            }
+            if (ch === '\\') {
+                escaped = true;
+                i++;
+                continue;
+            }
+            if (ch === quote)
+                quote = null;
+            i++;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === '`') {
+            quote = ch;
+            i++;
+            continue;
+        }
+        if (ch === '(')
+            depthParen++;
+        else if (ch === ')')
+            depthParen = Math.max(0, depthParen - 1);
+        else if (ch === '[')
+            depthBracket++;
+        else if (ch === ']')
+            depthBracket = Math.max(0, depthBracket - 1);
+        else if (ch === '{')
+            depthBrace++;
+        else if (ch === '}')
+            depthBrace = Math.max(0, depthBrace - 1);
+        if (depthParen !== 0 || depthBracket !== 0 || depthBrace !== 0) {
+            i++;
+            continue;
+        }
+        const rest = body.slice(i);
+        const returnMatch = /^return\b/.exec(rest);
+        if (!returnMatch) {
+            i++;
+            continue;
+        }
+        i += returnMatch[0].length;
+        while (i < body.length && /\s/.test(body[i]))
+            i++;
+        if (body[i] !== '{')
+            continue;
+        const closeIdx = findMatchingToken(body, i, '{', '}');
+        if (closeIdx === -1)
+            break;
+        const objectBody = body.slice(i + 1, closeIdx);
+        for (const rawProp of splitTopLevel(objectBody, ',')) {
+            const prop = rawProp.trim();
+            if (!prop || prop.startsWith('...'))
+                continue;
+            const keyMatch = prop.match(/^([A-Za-z_$][\w$]*)\s*(?::|$)/);
+            if (keyMatch)
+                pushIdentifier(keyMatch[1], keys);
+        }
+        break;
+    }
+    return keys;
+}
+function extractExplicitLoad(scriptBody) {
+    let i = 0;
+    let depthParen = 0;
+    let depthBracket = 0;
+    let depthBrace = 0;
+    let quote = null;
+    let escaped = false;
+    while (i < scriptBody.length) {
+        const ch = scriptBody[i];
+        if (quote) {
+            if (escaped) {
+                escaped = false;
+                i++;
+                continue;
+            }
+            if (ch === '\\') {
+                escaped = true;
+                i++;
+                continue;
+            }
+            if (ch === quote)
+                quote = null;
+            i++;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === '`') {
+            quote = ch;
+            i++;
+            continue;
+        }
+        if (ch === '(')
+            depthParen++;
+        else if (ch === ')')
+            depthParen = Math.max(0, depthParen - 1);
+        else if (ch === '[')
+            depthBracket++;
+        else if (ch === ']')
+            depthBracket = Math.max(0, depthBracket - 1);
+        else if (ch === '{')
+            depthBrace++;
+        else if (ch === '}')
+            depthBrace = Math.max(0, depthBrace - 1);
+        if (depthParen !== 0 || depthBracket !== 0 || depthBrace !== 0) {
+            i++;
+            continue;
+        }
+        const rest = scriptBody.slice(i);
+        const fnMatch = /^export\s+(async\s+)?function\s+load\s*/.exec(rest);
+        if (!fnMatch) {
+            i++;
+            continue;
+        }
+        const openParen = i + fnMatch[0].length;
+        if (scriptBody[openParen] !== '(') {
+            throw new Error('[kuratchi compiler] Could not parse exported load() declaration.');
+        }
+        const closeParen = findMatchingToken(scriptBody, openParen, '(', ')');
+        if (closeParen === -1) {
+            throw new Error('[kuratchi compiler] Could not parse exported load() parameters.');
+        }
+        let openBrace = closeParen + 1;
+        while (openBrace < scriptBody.length && /\s/.test(scriptBody[openBrace]))
+            openBrace++;
+        if (scriptBody[openBrace] !== '{') {
+            throw new Error('[kuratchi compiler] export load() must use a function body.');
+        }
+        const closeBrace = findMatchingToken(scriptBody, openBrace, '{', '}');
+        if (closeBrace === -1) {
+            throw new Error('[kuratchi compiler] Could not parse exported load() body.');
+        }
+        return {
+            loadFunction: scriptBody.slice(i, closeBrace + 1).trim(),
+            remainingScript: `${scriptBody.slice(0, i)}\n${scriptBody.slice(closeBrace + 1)}`.trim(),
+            returnVars: extractReturnObjectKeys(scriptBody.slice(openBrace + 1, closeBrace)),
+        };
+    }
+    return { loadFunction: null, remainingScript: scriptBody.trim(), returnVars: [] };
+}
+function hasFrameworkEnvEscapeHatch(source) {
+    return /\bglobalThis\.__cloudflare_env__\b/.test(source) || /\b__cloudflare_env__\b/.test(source);
+}
+function buildEnvAccessError(kind, filePath, detail) {
+    const label = filePath || kind;
+    const guidance = kind === 'route'
+        ? 'Route top-level <script> is server-side. Client/reactive scripts cannot access Cloudflare env.'
+        : kind === 'layout'
+            ? 'Layout scripts cannot access Cloudflare env directly.'
+            : 'Component scripts cannot access Cloudflare env directly.';
+    return new Error(`[kuratchi compiler] ${label}\n${detail}\n${guidance}\nRead env on the server and pass the value into the template explicitly.`);
+}
 function collectPatternNames(pattern, out) {
     const p = pattern.trim();
     if (!p)
@@ -401,22 +620,34 @@ function extractTopLevelFunctionNames(scriptBody) {
 /**
  * Parse a .html route file.
  *
- * The <script> block at the top is extracted for the compiler.
+ * The top-level compile-time <script> block is extracted for the compiler.
+ * If it includes reactive `$:` labels, it is preserved in template output.
  * Everything else (the HTML document) becomes the template.
  */
-export function parseFile(source) {
+export function parseFile(source, options = {}) {
+    const kind = options.kind || 'route';
     let script = null;
+    let clientScript = null;
     let template = source;
-    // Extract the first <script>...</script> block (the server-side framework script)
-    // Only match if it appears before any HTML document content
+    // Extract the first top-level compile-time <script>...</script> block.
+    // Client blocks (reactive `$:` labels) stay in the template
+    // and are emitted for browser execution.
     const scriptMatch = template.match(/^(\s*)<script(\s[^>]*)?\s*>([\s\S]*?)<\/script>/);
     if (scriptMatch) {
-        script = scriptMatch[3].trim();
-        template = template.slice(scriptMatch[0].length).trim();
+        const body = scriptMatch[3].trim();
+        if (!hasReactiveLabel(body)) {
+            script = body;
+            template = template.slice(scriptMatch[0].length).trim();
+        }
+        else {
+            clientScript = body;
+        }
     }
     // Extract all imports from script
     const serverImports = [];
+    const clientImports = [];
     const componentImports = {};
+    const workerEnvAliases = [];
     if (script) {
         // Support both single-line and multiline static imports.
         const importRegex = /^\s*import[\s\S]*?from\s+['"][^'"]+['"]\s*;?/gm;
@@ -440,24 +671,62 @@ export function parseFile(source) {
             else {
                 serverImports.push(line);
             }
+            for (const alias of extractCloudflareEnvAliases(line)) {
+                if (!workerEnvAliases.includes(alias))
+                    workerEnvAliases.push(alias);
+            }
+        }
+    }
+    if (clientScript) {
+        const importRegex = /^\s*import[\s\S]*?from\s+['"][^'"]+['"]\s*;?/gm;
+        let m;
+        while ((m = importRegex.exec(clientScript)) !== null) {
+            const line = m[0].trim();
+            clientImports.push(line);
+            if (extractCloudflareEnvAliases(line).length > 0) {
+                throw buildEnvAccessError(kind, options.filePath, 'Client <script> blocks cannot import env from cloudflare:workers.');
+            }
+        }
+        if (hasFrameworkEnvEscapeHatch(clientScript)) {
+            throw buildEnvAccessError(kind, options.filePath, 'Client <script> blocks cannot access framework env internals.');
         }
     }
     // Extract top-level variable declarations from script body (after removing imports)
     const dataVars = [];
+    const loadReturnVars = [];
     let scriptBody = '';
+    let loadFunction = null;
     if (script) {
         // Remove import lines to get the script body
-        scriptBody = script.replace(/^\s*import[\s\S]*?from\s+['"][^'"]+['"]\s*;?/gm, '').trim();
-        const topLevelVars = extractTopLevelDataVars(scriptBody);
+        const rawScriptBody = script.replace(/^\s*import[\s\S]*?from\s+['"][^'"]+['"]\s*;?/gm, '').trim();
+        const explicitLoad = extractExplicitLoad(rawScriptBody);
+        scriptBody = explicitLoad.remainingScript;
+        loadFunction = explicitLoad.loadFunction;
+        for (const name of explicitLoad.returnVars) {
+            if (!loadReturnVars.includes(name))
+                loadReturnVars.push(name);
+        }
+        if (hasFrameworkEnvEscapeHatch(rawScriptBody)) {
+            throw buildEnvAccessError(kind, options.filePath, 'Route/component scripts cannot access framework env internals.');
+        }
+        if (workerEnvAliases.length > 0 && kind !== 'route') {
+            throw buildEnvAccessError(kind, options.filePath, `Imported env from cloudflare:workers in a ${kind} script.`);
+        }
+        const transpiledScriptBody = transpileTypeScript(scriptBody, 'route-script.ts');
+        const topLevelVars = extractTopLevelDataVars(transpiledScriptBody);
         for (const v of topLevelVars)
             dataVars.push(v);
-        const topLevelFns = extractTopLevelFunctionNames(scriptBody);
+        const topLevelFns = extractTopLevelFunctionNames(transpiledScriptBody);
         for (const fn of topLevelFns) {
             if (!dataVars.includes(fn))
                 dataVars.push(fn);
         }
+        for (const name of loadReturnVars) {
+            if (!dataVars.includes(name))
+                dataVars.push(name);
+        }
     }
-    const hasLoad = scriptBody.length > 0;
+    const hasLoad = scriptBody.length > 0 || !!loadFunction;
     // Strip HTML comments from the template before scanning for action references.
     // This prevents commented-out code (<!-- ... -->) from being parsed as live
     // action expressions, which would cause false "Invalid action expression" errors.
@@ -530,5 +799,20 @@ export function parseFile(source) {
         if (!exists)
             dataGetQueries.push({ fnName, argsExpr, asName, key });
     }
-    return { script, template, serverImports, hasLoad, actionFunctions, dataVars, componentImports, pollFunctions, dataGetQueries };
+    return {
+        script,
+        loadFunction,
+        template,
+        serverImports,
+        hasLoad,
+        actionFunctions,
+        dataVars,
+        componentImports,
+        pollFunctions,
+        dataGetQueries,
+        clientImports,
+        loadReturnVars,
+        workerEnvAliases,
+    };
 }
+import { transpileTypeScript } from './transpile.js';

package/dist/compiler/template.d.ts

@@ -3,7 +3,9 @@
  *
  * Syntax:
  *   {expression}                → escaped output
- *   {=html expression}          → raw HTML output (unescaped)
+ *   {@html expression}          → sanitized HTML output
+ *   {@raw expression}           → raw HTML output (unescaped)
+ *   {=html expression}          → legacy alias for {@raw expression}
  *   for (const x of arr) {     → JS for loop (inline in HTML)
  *     <li>{x.name}</li>
  *   }