free-framework 4.4.0

package/compiler/analyzer.js

@@ -0,0 +1,102 @@
+/**
+ * compiler/analyzer.js
+ * Static Analysis pass for Free Framework.
+ * Detects errors before runtime:
+ *   - undefined views / pages
+ *   - unknown middleware references
+ *   - empty action bodies
+ *   - orphaned models (declared but not used)
+ *   - duplicate route paths
+ */
+
+function analyze(ast, filename = 'app') {
+    const warnings = [];
+    const errors = [];
+
+    function warn(msg, line) {
+        warnings.push({ type: 'warning', file: filename, line: line || 0, message: msg });
+    }
+    function error(msg, line) {
+        errors.push({ type: 'error', file: filename, line: line || 0, message: msg });
+    }
+
+    // Collect declared names (case-insensitive for comparison)
+    const declaredViews = new Set(ast.filter(n => n.type === 'page' || n.type === 'component').map(n => n.name.toLowerCase()));
+    const declaredModels = new Set(ast.filter(n => n.type === 'model').map(n => n.name));
+    const declaredActions = new Set(ast.filter(n => n.type === 'action').map(n => n.name));
+
+    const routePaths = new Map(); // path+method → line
+
+    ast.forEach(node => {
+        // ── Routes ──────────────────────────────────────────────────────────
+        if (node.type === 'route') {
+            // Check for undefined views
+            if (node.view && !declaredViews.has(node.view.toLowerCase())) {
+                warn(`Route "${node.method} ${node.path}" references undefined view "${node.view}". Did you forget to create ${node.view}.free?`, node.line);
+            }
+
+            // Check for duplicate routes
+            const routeKey = `${node.method}:${node.path}`;
+            if (routePaths.has(routeKey)) {
+                error(`Duplicate route: "${node.method} ${node.path}" is defined more than once.`, node.line);
+            }
+            routePaths.set(routeKey, node.line);
+        }
+
+        // ── Actions ──────────────────────────────────────────────────────────
+        if (node.type === 'action') {
+            if (!node.code || node.code.trim() === '') {
+                warn(`Action "${node.name}" has an empty body. It won't do anything.`, node.line);
+            }
+        }
+
+        // ── Models ───────────────────────────────────────────────────────────
+        if (node.type === 'model') {
+            if (!node.fields || node.fields.length === 0) {
+                warn(`Model "${node.name}" has no fields defined.`, node.line);
+            }
+        }
+
+        // ── Auth ──────────────────────────────────────────────────────────────
+        if (node.type === 'auth') {
+            if (!node.config.login && !node.config.register) {
+                warn(`"auth" block defined but neither login nor register paths are set.`);
+            }
+        }
+    });
+
+    return { errors, warnings, clean: errors.length === 0 };
+}
+
+/**
+ * Format analysis results for CLI output.
+ */
+function printAnalysis({ errors, warnings, clean }, filename) {
+    const colors = {
+        reset: '\x1b[0m',
+        red: '\x1b[31m',
+        yellow: '\x1b[33m',
+        green: '\x1b[32m',
+        gray: '\x1b[90m',
+        bold: '\x1b[1m',
+    };
+
+    if (errors.length === 0 && warnings.length === 0) {
+        console.log(`${colors.green}✅ ${filename}: No issues detected.${colors.reset}`);
+        return;
+    }
+
+    errors.forEach(e => {
+        console.error(`${colors.red}${colors.bold}ERROR${colors.reset} ${colors.gray}${e.file}:${e.line}${colors.reset} — ${e.message}`);
+    });
+
+    warnings.forEach(w => {
+        console.warn(`${colors.yellow}WARN${colors.reset}  ${colors.gray}${w.file}:${w.line}${colors.reset} — ${w.message}`);
+    });
+
+    if (!clean) {
+        console.error(`\n${colors.red}Found ${errors.length} error(s). Fix before building.${colors.reset}`);
+    }
+}
+
+module.exports = { analyze, printAnalysis };

package/compiler/generator.js

@@ -0,0 +1,386 @@
+/**
+ * compiler/generator.js
+ * Code Generator for Free Ultra (v4.3).
+ * Optimized for Islands Architecture and Component Composition.
+ */
+
+function generate(ast) {
+    let output = "require('dotenv').config();\n" +
+        "const { FreeServer } = require('free-framework/runtime/server');\n" +
+        "const { Model } = require('free-framework/database/model');\n" +
+        "const { ORM } = require('free-framework/database/orm');\n" +
+        "const { ClusterManager } = require('free-framework/runtime/cluster');\n" +
+        "const crypto = require('crypto');\n" +
+        "const bcrypt = require('bcryptjs');\n" +
+        "const jwt = require('jsonwebtoken');\n" +
+        "const fs = require('fs');\n" +
+        "const path = require('path');\n" +
+        "// Enterprise Services (Global Inject)\n" +
+        "let Validator, Storage;\n" +
+        "try { Validator = require(path.join(process.cwd(), 'app/Services/Validator.js')); } catch(e) {}\n" +
+        "try { Storage = require(path.join(process.cwd(), 'app/Services/Storage.js')); } catch(e) {}\n" +
+        "const server = new FreeServer();\n\n" +
+        "// Models\n" +
+        "const modelsRegistry = {};\n";
+
+    const CleanCSS = require('clean-css');
+    const glob = require('fs'); // Just using fs for readdirSync
+
+    const components = {};
+    const actions = {};
+    let globalCSS = "";
+
+    ast.forEach(node => {
+        if (node.type === 'action') actions[node.name] = node.code;
+    });
+
+    ast.forEach(node => {
+        if (node.type === 'model') {
+            output += `class ${node.name} extends Model {}\n${node.name}.fields = ${JSON.stringify(node.fields)};\n`;
+            output += `modelsRegistry['${node.name}'] = ${node.name};\n`;
+        }
+        if (node.type === 'component') {
+            components[node.name] = node;
+            const styles = node.body.filter(n => n.type === 'style');
+            styles.forEach(s => {
+                globalCSS += `.free-component[data-component="${node.name}"] { ${s.content} }\n`;
+                globalCSS += `.free-component:not([data-component]) { ${s.content} }\n`;
+            });
+        }
+        if (node.type === 'auth') {
+            const loginPath = node.config.login || '/login';
+            const registerPath = node.config.register || '/register';
+            output += `server.use(require('free-framework/plugins/auth')( ${JSON.stringify(node.config)} ));\n`;
+
+            output += `const loadAuthTemplate = (name, vars = {}) => {
+                const userTemplate = path.join(process.cwd(), 'resources/views/auth', name + '.html');
+                const coreTemplate = path.join(process.env.FREE_PATH || '', 'templates/auth', name + '.html');
+                let html = fs.existsSync(userTemplate) ? fs.readFileSync(userTemplate, 'utf8') : (fs.existsSync(coreTemplate) ? fs.readFileSync(coreTemplate, 'utf8') : 'Template not found');
+                Object.keys(vars).forEach(k => html = html.replace(new RegExp('{{' + k + '}}', 'g'), vars[k]));
+                return html;
+            };\n`;
+
+            output += `server.app.get('${loginPath}', (req, res) => {\n`;
+            output += `    res.header('Content-Type', 'text/html');\n`;
+            output += `    res.send(loadAuthTemplate('login', { registerPath: '${registerPath}' }));\n`;
+            output += `});\n`;
+            output += `server.app.get('${registerPath}', (req, res) => {\n`;
+            output += `    res.header('Content-Type', 'text/html');\n`;
+            output += `    res.send(loadAuthTemplate('register', { loginPath: '${loginPath}' }));\n`;
+            output += `});\n`;
+        }
+        if (node.type === 'upload') {
+            output += `server.use(require('free-framework/plugins/upload')('${node.name}', ${JSON.stringify(node.config)} ));\n`;
+        }
+        if (node.type === 'error') {
+            output += `server.setErrorView('${node.code}', '${node.view}');\n`;
+        }
+        if (node.type === 'validate') {
+            output += `server.registerMiddleware('validate:${node.model}', async (req, res, next) => {
+                const body = req.body || {};
+                const model = modelsRegistry['${node.model}'];
+                if (model && model.fields) {
+                    for (const field of model.fields) {
+                        if (field.required && !body[field.name]) {
+                            return res.status(400).json({ success: false, error: \`Field \${field.name} is required\` });
+                        }
+                    }
+                }
+                const rules = async () => { ${node.rules} };
+                try { await rules(); next(); } catch(e) { res.status(400).json({ success: false, error: e.message }); }
+            });\n`;
+        }
+        if (node.type === 'store') {
+            output += `server.store = server.store || {};\nserver.store['${node.name}'] = (() => { ${node.body} })();\n`;
+        }
+    });
+
+    output += `server.use(require('free-framework/plugins/chat')());\n`;
+
+    ast.forEach(node => {
+        if (node.type === 'action') {
+            output += `\nserver.app.post("/_free/action/${node.name}", async (req, res) => {
+    try {
+        const user = (res.context && res.context.user) ? res.context.user : null;
+        let body = {};
+        if (req.headers['content-type'] && req.headers['content-type'].includes('application/json')) {
+            body = await req.json().catch(() => ({}));
+        } else {
+            body = await req.urlencoded().catch(() => ({}));
+        }
+        const result = await (async () => {\n`;
+            if (node.params && node.params.length > 0) {
+                output += `          const { ${node.params.join(', ')} } = body;\n`;
+            }
+            output += "          " + node.code.replace(/res\.locals/g, 'res.context') + "\n" +
+                "        })();\n" +
+                "        if (!res.headersSent) res.json({ success: true, result });\n" +
+                "    } catch(e) {\n" +
+                "        if (!res.headersSent) res.status(500).json({ success: false, error: e.message });\n" +
+                "    }\n" +
+                "});\n";
+        }
+    });
+
+    globalCSS = new CleanCSS().minify(globalCSS).styles;
+    output += `\nconst scopedCSS = ${JSON.stringify(globalCSS.trim())};\n`;
+
+    output += `\nserver.renderRegistry = {\n`;
+    Object.keys(components).forEach((name, i) => {
+        output += `    ${name}: render${name}${i === Object.keys(components).length - 1 ? '' : ','}\n`;
+    });
+    output += `};\n`;
+
+    output += `\nserver.middleware((req, res, next) => {
+    if (!res.context) res.context = {};
+    res.context.csrfToken = crypto.randomBytes(32).toString('hex');
+    next();
+});\n`;
+
+    // Actually emit the component rendering functions (hoisted)
+    Object.values(components).forEach(node => {
+        output += generateUltraComponent(node);
+    });
+
+    // ── Auto-register Custom Middlewares from app/middleware ─────────────────
+    output += `
+const mwDir = path.join(process.cwd(), 'app/middleware');
+if (fs.existsSync(mwDir)) {
+    fs.readdirSync(mwDir).forEach(file => {
+        if (file.endsWith('.js')) {
+            const name = file.replace('.js', '');
+            server.registerMiddleware(name, require(path.join(mwDir, file)));
+        }
+    });
+}
+if (server.namedMiddlewares['auth']) server.namedMiddlewares['AuthGuard'] = server.namedMiddlewares['auth'];
+\n`;
+
+    ast.forEach(node => {
+        if (node.type === 'route') {
+            const v = node.view || 'home';
+            const viewName = v.charAt(0).toUpperCase() + v.slice(1);
+            const middlewares = node.middleware ? [node.middleware] : (node.middlewares || []);
+            let handlerCode = "";
+            if (node.handler && typeof node.handler === 'object' && node.handler.type === 'action_ref') {
+                handlerCode = actions[node.handler.name] || `console.error("Action not found: ${node.handler.name}");`;
+            } else {
+                handlerCode = node.handler || "";
+            }
+
+            output += `\nserver.route("${node.method.toLowerCase()}", "${node.path}", ${JSON.stringify(middlewares)}, async (req, res) => {
+        const user = (res.context && res.context.user) ? res.context.user : null;
+        let body = {};
+        try {
+            if (req.headers['content-type'] && req.headers['content-type'].includes('application/json')) {
+                body = await req.json().catch(() => ({}));
+            } else {
+                body = await req.urlencoded().catch(() => ({}));
+            }
+        } catch(e) {}
+
+        const result = await (async () => {\n` +
+                "            " + handlerCode.replace(/res\.locals/g, 'res.context') + "\n" +
+                "        })();\n\n" +
+                "        if (res.headersSent) return;\n" +
+                "\n" +
+                "        // If it's a PAGE route (has a view), render HTML\n" +
+                "        if (" + (node.view ? 'true' : 'false') + ") {\n" +
+                "            const helpers = {\n" +
+                "                renderComponent: (name, props = {}) => {\n" +
+                "                    server.renderRegistry = server.renderRegistry || {\n" +
+                "                        " + Object.keys(components).map(name => `${name}: render${name}`).join(',\n                        ') + "\n" +
+                "                    };\n" +
+                "                    return server.renderRegistry[name] ? server.renderRegistry[name](props, helpers) : '<!-- Component ' + name + ' not found -->';\n" +
+                "                }\n" +
+                "            };\n" +
+                "            const props = result || (res.context && res.context.props ? res.context.props : {});\n" +
+                "            const pageHtml = helpers.renderComponent('" + viewName + "', props);\n" +
+                "\n" +
+                "            if (req.headers['x-free-partial']) {\n" +
+                "                return res.json({ title: 'Free Ultra | " + viewName + "', content: pageHtml, url: req.url });\n" +
+                "            }\n" +
+                "\n" +
+                "            const headerHtml = helpers.renderComponent('Header', props);\n" +
+                "            const fullHTML = `<!DOCTYPE html><html lang=\"en\"><head>\n" +
+                "                <meta charset=\"UTF-8\"><title>Free Ultra | " + viewName + "</title>\n" +
+                "                <meta name=\"csrf-token\" content=\"${res.context.csrfToken || ''}\">\n" +
+                "                <link href=\"https://fonts.googleapis.com/css2?family=Outfit:wght@300;400;700;900&display=swap\" rel=\"stylesheet\">\n" +
+                "                <link rel=\"stylesheet\" href=\"/css/app.css\">\n" +
+                "                <style>\n" +
+                "                    :root { --primary:#00ff88; --secondary:#00bdff; --dark:#050505; }\n" +
+                "                    * { box-sizing:border-box; }\n" +
+                "                    body { margin:0; font-family:'Outfit',sans-serif; background:var(--dark); color:white; overflow-x:hidden; scroll-behavior:smooth; }\n" +
+                "                    main { width:100%; max-width:1000px; margin:0 auto; padding:6rem 2rem 2rem; min-height:100vh; }\n" +
+                "                    ${scopedCSS}\n" +
+                "                </style>\n" +
+                "                <script src=\"/free-runtime.js\" defer></script></head>\n" +
+                "                <body>${headerHtml}<main id=\"free-app-root\">${pageHtml}</main></body></html>`;\n" +
+                "            const minified = await minify(fullHTML, { collapseWhitespace: true, removeComments: true, continueOnParseError: true });\n" +
+                "            res.header('Content-Type', 'text/html').send(fullHTML);\n" +
+                "        } else {\n" +
+                "            // API route - return JSON\n" +
+                "            res.json({ success: true, result });\n" +
+                "        }\n" +
+                "});\n";
+        }
+    });
+
+    output += `\nif (require.main === module) {
+    ORM.migrate(modelsRegistry).then(() => {
+        server.start(process.env.PORT || 4000);
+    }).catch(err => console.error(err));
+}
+
+module.exports = { ...modelsRegistry, server, modelsRegistry, ORM };
+`;
+
+    return output;
+}
+
+function generateUltraComponent(node) {
+    const onMount = node.body.find(n => n.type === 'onMount')?.code || '';
+    const onDestroy = node.body.find(n => n.type === 'onDestroy')?.code || '';
+    const isInteractive = node.states.length > 0 || onMount !== '' || onDestroy !== '' || hasInteractivity(node.body);
+    const stateNames = node.states.map(s => s.name);
+
+    let code = `\nfunction render${node.name}(props = { }, helpers = { }) {\n`;
+    code += `    const e = (str) => String(str).replace(/[&<>'"]/g, m => ({'&': '&amp;', '<': '&lt;', '>': '&gt;', "'": '&#39;', '"': '&quot;' }[m]));\n`;
+    code += `    const state = {\n`;
+    node.states.forEach(s => {
+        let val = s.default;
+        const isExpression = typeof val === 'string' && (val.includes('props.') || val.includes('||') || val.includes('&&') || val === 'true' || val === 'false' || val === 'null' || val.trim().startsWith('{') || val.trim().startsWith('['));
+        const finalVal = (isExpression || typeof val === 'number') ? val : `"${val}"`;
+        code += `        "${s.name}": ${finalVal},\n`;
+    });
+    code += `    };\n`;
+    if (stateNames.length > 0) {
+        code += `    const { ${stateNames.join(', ')} } = state;\n`;
+    }
+
+    code += `    const _events = [];\n`;
+    code += `    const islandAttr = ${isInteractive} ? ' data-component="${node.name}"' : '';\n`;
+    code += `    let html = "<div class='free-component'" + islandAttr + " data-state='" + JSON.stringify(state).replace(/'/g, "&#39;") + "'";\n`;
+
+    if (onMount) {
+        code += `    _events.push({ id: 'onMount', fn: function(state) { ${onMount} } });\n`;
+        code += `    html += " data-free-on-mount='onMount'";\n`;
+    }
+    if (onDestroy) {
+        code += `    _events.push({ id: 'onDestroy', fn: function(state) { ${onDestroy} } });\n`;
+        code += `    html += " data-free-on-destroy='onDestroy'";\n`;
+    }
+
+    code += `    html += ">";\n`;
+    code += generateComponentBody(node.body, stateNames);
+
+    if (isInteractive) {
+        code += `    html += "<script>window.__free_actions = window.__free_actions || {}; window.__free_actions['${node.name}'] = {};";\n`;
+        code += `    _events.forEach(ev => {\n`;
+        code += `        html += "window.__free_actions['${node.name}'][ev.id] = " + ev.fn.toString() + ";";\n`;
+        code += `    });\n`;
+        code += `    html += "</script>";\n`;
+    }
+
+    code += `    html += "</div>";\n    return html;\n}\n`;
+    return code;
+}
+
+function generateComponentBody(body, stateNames) {
+    let code = "";
+    body.forEach(node => {
+        if (node.type === 'tag') {
+            code += generateTagCode(node, stateNames);
+        } else if (node.type === 'event') {
+            return;
+        } else if (node.type === 'script') {
+            const scriptCode = node.code.replace(/`/g, '\\`').replace(/\$/g, '\\$');
+            code += `    html += \`<script>${scriptCode}</script>\`;\n`;
+        } else if (node.type === 'loop') {
+            code += "    if (Array.isArray(" + node.list + ")) {\n";
+            code += "        " + node.list + ".forEach(" + node.item + " => {\n";
+            code += generateComponentBody(node.body, stateNames).replace(/^    /gm, '        ');
+            code += "        });\n";
+            code += "    }\n";
+        } else if (node.type === 'condition') {
+            code += "    if (" + node.condition + ") {\n";
+            code += generateComponentBody(node.body, stateNames).replace(/^    /gm, '        ');
+            code += "    }\n";
+        }
+    });
+    return code;
+}
+
+function hasInteractivity(nodes) {
+    return nodes.some(n => {
+        if (n.type === 'tag') {
+            if (n.attributes && Object.keys(n.attributes).some(a => a.startsWith('on'))) return true;
+            if (n.children && hasInteractivity(n.children)) return true;
+        }
+        return false;
+    });
+}
+
+function generateTagCode(tag, stateNames) {
+    const isComponent = tag.name[0] === tag.name[0].toUpperCase();
+    if (isComponent) {
+        let propsStr = "{";
+        if (tag.attributes) {
+            Object.keys(tag.attributes).forEach((a, i) => {
+                let val = tag.attributes[a].replace(/\{([^}]+)\}/g, (_, p) => "${" + p + "}");
+                propsStr += (i === 0 ? "" : ", ") + '"' + a + '": `' + val + '`';
+            });
+        }
+        propsStr += "}";
+        return `    html += helpers.renderComponent('${tag.name}', ${propsStr}, helpers);\n`;
+    }
+
+    let code = `    html += "<${tag.name}";\n`;
+
+    if (tag.attributes) {
+        Object.keys(tag.attributes).forEach(a => {
+            if (a.startsWith('on')) {
+                const eventName = a.substring(2).toLowerCase();
+                const uniqueId = `\${eventName}_\${tag.name}_\${Math.random().toString(36).substring(7)}`;
+                if (tag.attributes[a].includes('++')) {
+                    const key = tag.attributes[a].split('++')[0].trim();
+                    code += `    _events.push({ id: '${uniqueId}', fn: function(state) { state['${key}']++; } });\n`;
+                } else {
+                    code += `    _events.push({ id: '${uniqueId}', fn: function(state, event) { ${tag.attributes[a]} } });\n`;
+                }
+                code += `    html += " data-on-${eventName}='${uniqueId}'";\n`;
+            } else {
+                let val = tag.attributes[a].replace(/\{([^}]+)\}/g, (_, p) => "${e(" + p + ")}");
+                code += "    html += \" \" + " + JSON.stringify(a) + " + \"='\" + `" + val + "` + \"'\";\n";
+            }
+        });
+    }
+
+    if (tag.children) {
+        tag.children.forEach(child => {
+            if (child.type === 'event') {
+                const eventName = child.event.toLowerCase();
+                const uniqueId = `\${eventName}_child_\${Math.random().toString(36).substring(7)}`;
+                code += `    _events.push({ id: '${uniqueId}', fn: function(state, event) { ${child.code} } });\n`;
+                code += `    html += " data-on-${eventName}='${uniqueId}'";\n`;
+            }
+        });
+    }
+
+    code += `    html += ">";\n`;
+
+    if (tag.content) {
+        let cont = tag.content.replace(/`/g, '\\`').replace(/\$/g, '\\$').replace(/\{([^}]+)\}/g, (_, p) => {
+            const parts = p.split('.');
+            if (stateNames.includes(parts[0])) return `\${e(state["${parts[0]}"]${parts.slice(1).map(part => `?.["${part}"]`).join('')})}`;
+            return `\${e(${p})}`;
+        });
+        code += `    html += \`${cont}\`;\n`;
+    }
+
+    if (tag.children) code += generateComponentBody(tag.children, stateNames);
+    code += `    html += "</${tag.name}>";\n`;
+    return code;
+}
+
+module.exports = { generate };

package/compiler/lexer.js

@@ -0,0 +1,166 @@
+/**
+ * compiler/lexer.js
+ * Lexer for the Free Framework.
+ * Converts .free code into tokens WITH line & column tracking.
+ */
+
+class FreeSyntaxError extends SyntaxError {
+    constructor(message, file, line, col) {
+        super(message);
+        this.name = 'FreeSyntaxError';
+        this.file = file || 'unknown.free';
+        this.line = line;
+        this.col = col;
+    }
+
+    toString() {
+        return `\n\x1b[31mFreeSyntaxError\x1b[0m in \x1b[33m${this.file}\x1b[0m\n` +
+            `  Line ${this.line}, Col ${this.col}: ${this.message}\n`;
+    }
+}
+
+const KEYWORDS = new Set([
+    'route', 'model', 'component', 'page', 'view', 'link', 'state', 'on', 'style',
+    'middleware', 'auth', 'login', 'register', 'upload', 'path', 'maxSize', 'error',
+    'text', 'action', 'validate', 'store', 'onMount', 'onDestroy', 'queue', 'mail',
+    'loop', 'condition', 'script', 'if', 'for'
+]);
+
+function tokenize(code, filename = 'unknown.free') {
+    const tokens = [];
+    let i = 0;
+    let line = 1;
+    let col = 1;
+
+    while (i < code.length) {
+        const ch = code[i];
+
+        // Skip whitespace, track position
+        if (ch === '\n') {
+            line++;
+            col = 1;
+            i++;
+            continue;
+        }
+        if (ch === '\r' || ch === '\t' || ch === ' ') {
+            col++;
+            i++;
+            continue;
+        }
+
+        // Single-line comments  // ...
+        if (ch === '/' && code[i + 1] === '/') {
+            while (i < code.length && code[i] !== '\n') i++;
+            continue;
+        }
+
+        // Multi-line block comments /* ... */
+        if (ch === '/' && code[i + 1] === '*') {
+            i += 2; // skip /*
+            while (i < code.length && !(code[i] === '*' && code[i + 1] === '/')) {
+                if (code[i] === '\n') {
+                    line++;
+                    col = 1;
+                } else {
+                    col++;
+                }
+                i++;
+            }
+            i += 2; // skip */
+            col += 2;
+            continue;
+        }
+
+        // Strings "...", '...', `...`
+        if (ch === '"' || ch === "'" || ch === '`') {
+            const quoteStart = ch;
+            const startLine = line;
+            const startCol = col;
+            const startIdx = i;
+            let str = '';
+            i++; col++;
+            while (i < code.length && code[i] !== quoteStart) {
+                // Handle escapes
+                if (code[i] === '\\') {
+                    str += code[i];
+                    i++; col++;
+                    str += code[i];
+                    i++; col++;
+                    continue;
+                }
+
+                if (code[i] === '\n') {
+                    if (quoteStart !== '`') {
+                        throw new FreeSyntaxError('Unterminated string literal', filename, startLine, startCol);
+                    }
+                    line++;
+                    col = 1;
+                } else {
+                    col++;
+                }
+
+                str += code[i];
+                i++;
+            }
+            if (i >= code.length) {
+                throw new FreeSyntaxError('Unterminated string literal', filename, startLine, startCol);
+            }
+            i++; col++; // closing quote
+            tokens.push({ type: 'STRING', value: `${quoteStart}${str}${quoteStart}`, raw: str, line: startLine, col: startCol, start: startIdx, end: i });
+            continue;
+        }
+
+        // Braces
+        if (ch === '{' || ch === '}') {
+            tokens.push({ type: 'BRACE', value: ch, line, col, start: i, end: i + 1 });
+            i++; col++;
+            continue;
+        }
+
+        // Parens
+        if (ch === '(' || ch === ')') {
+            tokens.push({ type: 'PAREN', value: ch, line, col, start: i, end: i + 1 });
+            i++; col++;
+            continue;
+        }
+
+        // Numbers
+        if (ch >= '0' && ch <= '9') {
+            const startCol = col;
+            const startLine = line;
+            const startIdx = i;
+            let num = '';
+            while (i < code.length && code[i] >= '0' && code[i] <= '9') {
+                num += code[i];
+                i++; col++;
+            }
+            tokens.push({ type: 'NUMBER', value: num, line: startLine, col: startCol, start: startIdx, end: i });
+            continue;
+        }
+
+        // Identifiers and Keywords
+        if ((ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z') || ch === '_') {
+            const startCol = col;
+            const startLine = line;
+            const startIdx = i;
+            let word = '';
+            while (i < code.length && /[\w\-]/.test(code[i])) {
+                word += code[i];
+                i++; col++;
+            }
+            const type = KEYWORDS.has(word) ? 'KEYWORD' : 'IDENTIFIER';
+            tokens.push({ type, value: word, line: startLine, col: startCol, start: startIdx, end: i });
+            continue;
+        }
+
+        // Symbols (operators, punctuation)
+        const symStart = col;
+        const startIdx = i;
+        tokens.push({ type: 'SYMBOL', value: ch, line, col: symStart, start: startIdx, end: i + 1 });
+        i++; col++;
+    }
+
+    return tokens;
+}
+
+module.exports = { tokenize, FreeSyntaxError, KEYWORDS };