dalila 1.9.2 → 1.9.3

package/README.md

@@ -7,7 +7,7 @@ Dalila is a reactive framework built on signals. No virtual DOM, no JSX required
 ## Quick Start
 
 ```bash
-npm create dalila my-app
+npm create dalila@latest my-app
 cd my-app
 npm install
 npm run dev
@@ -64,6 +64,7 @@ bind(document.getElementById('app')!, ctx);
 ### Routing
 
 - [Router](./docs/router.md) — Client-side routing with nested layouts, preloading, and file-based route generation
+- [Template Check CLI](./docs/cli/check.md) — `dalila check` static analysis for template/context consistency
 
 ### UI Components
 
@@ -214,7 +215,7 @@ src/app/
 ```
 
 ```bash
-dalila routes generate
+npx dalila routes generate
 ```
 
 ```ts

package/dist/cli/check.d.ts

@@ -0,0 +1,3 @@
+export declare function runCheck(appDir: string, options?: {
+    strict?: boolean;
+}): Promise<number>;

package/dist/cli/check.js

@@ -0,0 +1,902 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { buildRouteTree, injectHtmlPathTemplates, findFile, findProjectRoot, extractParamKeys, } from './routes-generator.js';
+// ============================================================================
+// TypeScript Compiler API (dynamic import)
+// ============================================================================
+async function loadTypeScript() {
+    try {
+        return await import('typescript');
+    }
+    catch {
+        console.error('❌ TypeScript is required for `dalila check`.\n' +
+            '   Install it with: npm install -D typescript');
+        process.exit(1);
+    }
+}
+// ============================================================================
+// Loader return type extraction via TS Compiler API
+// ============================================================================
+function extractLoaderReturnKeys(ts, checker, loaderSymbol, sourceFile) {
+    function isPlainObjectLikeType(type) {
+        if (type.isUnion()) {
+            return type.types.length > 0 && type.types.every(isPlainObjectLikeType);
+        }
+        if (type.isIntersection()) {
+            return type.types.length > 0 && type.types.every(isPlainObjectLikeType);
+        }
+        if ((type.flags & ts.TypeFlags.Object) === 0)
+            return false;
+        const objectType = type;
+        if (objectType.getCallSignatures().length > 0)
+            return false;
+        if (checker.isArrayType(type) || checker.isTupleType(type))
+            return false;
+        const objectFlags = objectType.objectFlags ?? 0;
+        if ((objectFlags & ts.ObjectFlags.Reference) !== 0) {
+            const target = objectType.target;
+            const targetName = target?.symbol?.getName();
+            if (targetName === 'Array' || targetName === 'ReadonlyArray')
+                return false;
+        }
+        return true;
+    }
+    const resolvedLoaderSymbol = loaderSymbol.flags & ts.SymbolFlags.Alias
+        ? checker.getAliasedSymbol(loaderSymbol)
+        : loaderSymbol;
+    const loaderLocation = resolvedLoaderSymbol.valueDeclaration ??
+        resolvedLoaderSymbol.declarations?.[0] ??
+        sourceFile;
+    const loaderType = checker.getTypeOfSymbolAtLocation(resolvedLoaderSymbol, loaderLocation);
+    const callSignatures = loaderType.getCallSignatures();
+    if (callSignatures.length === 0)
+        return null;
+    let returnType = checker.getReturnTypeOfSignature(callSignatures[0]);
+    // Unwrap Promise<T>
+    const typeSymbol = returnType.getSymbol();
+    const targetSymbol = returnType.target?.symbol;
+    if (typeSymbol?.getName() === 'Promise' ||
+        targetSymbol?.getName() === 'Promise') {
+        const typeArgs = checker.getTypeArguments(returnType);
+        if (typeArgs && typeArgs.length > 0) {
+            returnType = typeArgs[0];
+        }
+    }
+    if (!isPlainObjectLikeType(returnType))
+        return null;
+    return returnType.getProperties().map(p => p.getName());
+}
+function getLoaderExportSymbol(ts, checker, sourceFile) {
+    const symbol = checker.getSymbolAtLocation(sourceFile);
+    if (!symbol)
+        return null;
+    const moduleExports = checker.getExportsOfModule(symbol);
+    const loaderSymbol = moduleExports.find(s => s.getName() === 'loader');
+    if (!loaderSymbol)
+        return null;
+    const runtimeFlags = ts.SymbolFlags.Function |
+        ts.SymbolFlags.Variable |
+        ts.SymbolFlags.Property |
+        ts.SymbolFlags.Method |
+        ts.SymbolFlags.GetAccessor |
+        ts.SymbolFlags.Alias;
+    return (loaderSymbol.flags & runtimeFlags) !== 0 ? loaderSymbol : null;
+}
+// ============================================================================
+// Template identifier extraction (regex-based)
+// ============================================================================
+const JS_KEYWORDS = new Set([
+    'true', 'false', 'null', 'undefined', 'NaN', 'Infinity',
+    'typeof', 'instanceof', 'void', 'delete', 'in', 'of',
+    'new', 'this', 'if', 'else', 'return', 'switch', 'case',
+    'break', 'continue', 'for', 'while', 'do', 'try', 'catch',
+    'finally', 'throw', 'const', 'let', 'var', 'function', 'class',
+]);
+function extractParamNames(segment) {
+    const result = [];
+    const seen = new Set();
+    const IDENT_RE = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+    function splitTopLevel(input) {
+        const parts = [];
+        let start = 0;
+        let depthParen = 0;
+        let depthBracket = 0;
+        let depthBrace = 0;
+        let inString = null;
+        let escaped = false;
+        for (let i = 0; i < input.length; i++) {
+            const ch = input[i];
+            if (inString) {
+                if (escaped) {
+                    escaped = false;
+                }
+                else if (ch === '\\') {
+                    escaped = true;
+                }
+                else if (ch === inString) {
+                    inString = null;
+                }
+                continue;
+            }
+            if (ch === '"' || ch === "'" || ch === '`') {
+                inString = ch;
+                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);
+            else if (ch === ',' &&
+                depthParen === 0 &&
+                depthBracket === 0 &&
+                depthBrace === 0) {
+                parts.push(input.slice(start, i));
+                start = i + 1;
+            }
+        }
+        parts.push(input.slice(start));
+        return parts;
+    }
+    function topLevelIndexOf(input, target) {
+        let depthParen = 0;
+        let depthBracket = 0;
+        let depthBrace = 0;
+        let inString = null;
+        let escaped = false;
+        for (let i = 0; i < input.length; i++) {
+            const ch = input[i];
+            if (inString) {
+                if (escaped) {
+                    escaped = false;
+                }
+                else if (ch === '\\') {
+                    escaped = true;
+                }
+                else if (ch === inString) {
+                    inString = null;
+                }
+                continue;
+            }
+            if (ch === '"' || ch === "'" || ch === '`') {
+                inString = ch;
+                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);
+            else if (ch === target &&
+                depthParen === 0 &&
+                depthBracket === 0 &&
+                depthBrace === 0) {
+                return i;
+            }
+        }
+        return -1;
+    }
+    function stripDefaultValue(input) {
+        const eqIdx = topLevelIndexOf(input, '=');
+        if (eqIdx >= 0)
+            return input.slice(0, eqIdx).trim();
+        return input.trim();
+    }
+    function collectFromPattern(pattern) {
+        let param = pattern.trim();
+        if (!param)
+            return;
+        param = param.replace(/^\.\.\./, '').trim();
+        param = stripDefaultValue(param);
+        if (!param)
+            return;
+        if (IDENT_RE.test(param)) {
+            if (!JS_KEYWORDS.has(param) && !seen.has(param)) {
+                seen.add(param);
+                result.push(param);
+            }
+            return;
+        }
+        if (param.startsWith('{') && param.endsWith('}')) {
+            const inner = param.slice(1, -1);
+            for (const rawEntry of splitTopLevel(inner)) {
+                const entry = rawEntry.trim();
+                if (!entry)
+                    continue;
+                if (entry.startsWith('...')) {
+                    collectFromPattern(entry.slice(3));
+                    continue;
+                }
+                const colonIdx = topLevelIndexOf(entry, ':');
+                if (colonIdx >= 0) {
+                    collectFromPattern(entry.slice(colonIdx + 1));
+                }
+                else {
+                    collectFromPattern(entry);
+                }
+            }
+            return;
+        }
+        if (param.startsWith('[') && param.endsWith(']')) {
+            const inner = param.slice(1, -1);
+            for (const rawEntry of splitTopLevel(inner)) {
+                collectFromPattern(rawEntry);
+            }
+        }
+    }
+    for (const chunk of splitTopLevel(segment)) {
+        collectFromPattern(chunk);
+    }
+    return result;
+}
+function collectLocalIdentifiers(expr) {
+    const locals = new Set();
+    const ARROW_SINGLE_PARAM_RE = /(?<![\w$.])([a-zA-Z_$][a-zA-Z0-9_$]*)\s*=>/g;
+    let match;
+    while ((match = ARROW_SINGLE_PARAM_RE.exec(expr))) {
+        locals.add(match[1]);
+    }
+    const ARROW_PARAMS_RE = /\(([^)]*)\)\s*=>/g;
+    while ((match = ARROW_PARAMS_RE.exec(expr))) {
+        for (const name of extractParamNames(match[1])) {
+            locals.add(name);
+        }
+    }
+    const FUNCTION_PARAMS_RE = /function(?:\s+[a-zA-Z_$][a-zA-Z0-9_$]*)?\s*\(([^)]*)\)/g;
+    while ((match = FUNCTION_PARAMS_RE.exec(expr))) {
+        for (const name of extractParamNames(match[1])) {
+            locals.add(name);
+        }
+    }
+    const CATCH_PARAM_RE = /catch\s*\(\s*([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\)/g;
+    while ((match = CATCH_PARAM_RE.exec(expr))) {
+        locals.add(match[1]);
+    }
+    return locals;
+}
+/**
+ * Extract root identifiers from a template expression.
+ * Given `items.length`, returns `['items']`.
+ * Given `count`, returns `['count']`.
+ * Ignores string literals, numbers, and JS keywords.
+ */
+function extractRootIdentifiers(expr) {
+    // Remove plain string literal contents while preserving template
+    // expression bodies inside `${...}` so identifiers are still validated.
+    const stripStringsPreserveTemplateExpressions = (input) => {
+        let i = 0;
+        let out = '';
+        const consumeQuoted = (quote) => {
+            out += ' ';
+            i++;
+            let escaped = false;
+            while (i < input.length) {
+                const ch = input[i];
+                out += ' ';
+                i++;
+                if (escaped) {
+                    escaped = false;
+                    continue;
+                }
+                if (ch === '\\') {
+                    escaped = true;
+                    continue;
+                }
+                if (ch === quote)
+                    break;
+            }
+        };
+        const consumeTemplate = () => {
+            out += ' ';
+            i++;
+            let escaped = false;
+            while (i < input.length) {
+                const ch = input[i];
+                if (escaped) {
+                    out += ' ';
+                    escaped = false;
+                    i++;
+                    continue;
+                }
+                if (ch === '\\') {
+                    out += ' ';
+                    escaped = true;
+                    i++;
+                    continue;
+                }
+                if (ch === '`') {
+                    out += ' ';
+                    i++;
+                    break;
+                }
+                if (ch === '$' && input[i + 1] === '{') {
+                    out += '${';
+                    i += 2;
+                    let depth = 1;
+                    while (i < input.length && depth > 0) {
+                        const inner = input[i];
+                        if (inner === '"' || inner === "'") {
+                            consumeQuoted(inner);
+                            continue;
+                        }
+                        if (inner === '`') {
+                            consumeTemplate();
+                            continue;
+                        }
+                        if (inner === '{') {
+                            depth++;
+                            out += inner;
+                            i++;
+                            continue;
+                        }
+                        if (inner === '}') {
+                            depth--;
+                            out += inner;
+                            i++;
+                            continue;
+                        }
+                        out += inner;
+                        i++;
+                    }
+                    continue;
+                }
+                out += ' ';
+                i++;
+            }
+        };
+        while (i < input.length) {
+            const ch = input[i];
+            if (ch === '"' || ch === "'") {
+                consumeQuoted(ch);
+                continue;
+            }
+            if (ch === '`') {
+                consumeTemplate();
+                continue;
+            }
+            out += ch;
+            i++;
+        }
+        return out;
+    };
+    const cleaned = stripStringsPreserveTemplateExpressions(expr);
+    const localIdentifiers = collectLocalIdentifiers(cleaned);
+    // Match identifiers NOT preceded by a dot (member access)
+    const regex = /(?<![.\w$])([a-zA-Z_$][a-zA-Z0-9_$]*)/g;
+    const seen = new Set();
+    const result = [];
+    const prevNonWs = (index) => {
+        for (let i = index; i >= 0; i--) {
+            if (!/\s/.test(cleaned[i]))
+                return cleaned[i];
+        }
+        return null;
+    };
+    const nextNonWs = (index) => {
+        for (let i = index; i < cleaned.length; i++) {
+            if (!/\s/.test(cleaned[i]))
+                return cleaned[i];
+        }
+        return null;
+    };
+    let match;
+    while ((match = regex.exec(cleaned))) {
+        const name = match[1];
+        const nextToken = nextNonWs(regex.lastIndex);
+        const prevToken = prevNonWs(match.index - 1);
+        const isObjectLiteralKey = nextToken === ':' && (prevToken === '{' || prevToken === ',');
+        if (!isObjectLiteralKey && !JS_KEYWORDS.has(name) && !seen.has(name) && !localIdentifiers.has(name)) {
+            seen.add(name);
+            result.push(name);
+        }
+    }
+    return result;
+}
+/**
+ * Extract all template identifiers from HTML content.
+ *
+ * Scans for:
+ * 1. Text interpolation `{expr}` — only outside HTML tags
+ * 2. Context-binding directives `d-*="value"` — specific set
+ */
+function extractTemplateIdentifiers(html) {
+    const identifiers = [];
+    const lines = html.split('\n');
+    const lineOffsets = [];
+    let runningOffset = 0;
+    for (const line of lines) {
+        lineOffsets.push(runningOffset);
+        runningOffset += line.length + 1;
+    }
+    function offsetToLineCol(offset) {
+        let lineIdx = 0;
+        for (let i = 0; i < lineOffsets.length; i++) {
+            if (lineOffsets[i] <= offset) {
+                lineIdx = i;
+            }
+            else {
+                break;
+            }
+        }
+        return { line: lineIdx + 1, col: offset - lineOffsets[lineIdx] + 1 };
+    }
+    // --- 1. Text interpolation {expr} with state machine (supports multiline) ---
+    let inTag = false;
+    let tagQuote = null;
+    let i = 0;
+    while (i < html.length) {
+        const ch = html[i];
+        if (!inTag && ch === '<') {
+            inTag = true;
+            tagQuote = null;
+            i++;
+            continue;
+        }
+        if (inTag) {
+            if (tagQuote) {
+                if (ch === tagQuote) {
+                    tagQuote = null;
+                }
+                i++;
+                continue;
+            }
+            if (ch === '"' || ch === "'") {
+                tagQuote = ch;
+                i++;
+                continue;
+            }
+            if (ch === '>') {
+                inTag = false;
+                tagQuote = null;
+                i++;
+                continue;
+            }
+            i++;
+            continue;
+        }
+        if (ch === '{') {
+            const start = i;
+            let depth = 1;
+            let j = i + 1;
+            let inString = null;
+            let escaped = false;
+            while (j < html.length && depth > 0) {
+                const ch = html[j];
+                if (inString) {
+                    if (escaped) {
+                        escaped = false;
+                    }
+                    else if (ch === '\\') {
+                        escaped = true;
+                    }
+                    else if (ch === inString) {
+                        inString = null;
+                    }
+                    j++;
+                    continue;
+                }
+                if (ch === '"' || ch === "'" || ch === '`') {
+                    inString = ch;
+                    j++;
+                    continue;
+                }
+                if (ch === '{')
+                    depth++;
+                if (ch === '}')
+                    depth--;
+                j++;
+            }
+            if (depth === 0) {
+                const expr = html.slice(start + 1, j - 1);
+                const roots = extractRootIdentifiers(expr);
+                const loc = offsetToLineCol(start);
+                for (const name of roots) {
+                    identifiers.push({
+                        name,
+                        line: loc.line,
+                        col: loc.col,
+                        offset: start,
+                        source: 'interpolation',
+                    });
+                }
+                i = j;
+                continue;
+            }
+        }
+        i++;
+    }
+    // --- 2. Directive scanning (supports single and double quotes) ---
+    const DIRECTIVE_RE = /\b(d-each|d-virtual-each|d-virtual-height|d-virtual-item-height|d-virtual-overscan|d-if|d-when|d-match|d-html|d-attr-[a-zA-Z][\w-]*|d-on-[a-zA-Z][\w-]*|d-form-error|d-form|d-array)\s*=\s*(['"])([\s\S]*?)\2/g;
+    DIRECTIVE_RE.lastIndex = 0;
+    let match;
+    while ((match = DIRECTIVE_RE.exec(html))) {
+        const directive = match[1];
+        const value = match[3].trim();
+        if (!value)
+            continue;
+        const roots = extractRootIdentifiers(value);
+        const loc = offsetToLineCol(match.index);
+        for (const name of roots) {
+            identifiers.push({
+                name,
+                line: loc.line,
+                col: loc.col,
+                offset: match.index,
+                source: directive,
+            });
+        }
+    }
+    return identifiers;
+}
+function extractLoopRanges(html) {
+    const ranges = [];
+    const stack = [];
+    let i = 0;
+    while (i < html.length) {
+        if (html[i] !== '<') {
+            i++;
+            continue;
+        }
+        let j = i + 1;
+        let inString = null;
+        let escaped = false;
+        while (j < html.length) {
+            const ch = html[j];
+            if (inString) {
+                if (escaped) {
+                    escaped = false;
+                }
+                else if (ch === '\\') {
+                    escaped = true;
+                }
+                else if (ch === inString) {
+                    inString = null;
+                }
+                j++;
+                continue;
+            }
+            if (ch === '"' || ch === "'") {
+                inString = ch;
+                j++;
+                continue;
+            }
+            if (ch === '>')
+                break;
+            j++;
+        }
+        if (j >= html.length)
+            break;
+        const fullTag = html.slice(i, j + 1);
+        const inner = html.slice(i + 1, j).trim();
+        const isClosingTag = inner.startsWith('/');
+        const normalized = isClosingTag ? inner.slice(1).trim() : inner;
+        const nameMatch = /^([a-zA-Z][\w:-]*)/.exec(normalized);
+        if (!nameMatch) {
+            i = j + 1;
+            continue;
+        }
+        const tagName = nameMatch[1];
+        const attrs = normalized.slice(tagName.length);
+        const isSelfClosingTag = !isClosingTag && /\/\s*$/.test(normalized);
+        if (isClosingTag) {
+            for (let stackIdx = stack.length - 1; stackIdx >= 0; stackIdx--) {
+                if (stack[stackIdx].tagName !== tagName)
+                    continue;
+                const entry = stack.splice(stackIdx, 1)[0];
+                if (entry.isLoop) {
+                    ranges.push({ start: entry.start, end: i + fullTag.length });
+                }
+                break;
+            }
+            i = j + 1;
+            continue;
+        }
+        const isLoopTag = /\bd-(?:virtual-)?each\s*=\s*(['"])([\s\S]*?)\1/.test(attrs);
+        if (isSelfClosingTag) {
+            if (isLoopTag) {
+                ranges.push({ start: i, end: i + fullTag.length });
+            }
+            i = j + 1;
+            continue;
+        }
+        stack.push({ tagName, isLoop: isLoopTag, start: i });
+        i = j + 1;
+    }
+    for (const entry of stack) {
+        if (entry.isLoop) {
+            ranges.push({ start: entry.start, end: html.length });
+        }
+    }
+    return ranges;
+}
+function isInsideLoopRange(offset, ranges) {
+    for (const range of ranges) {
+        if (offset >= range.start && offset < range.end)
+            return true;
+    }
+    return false;
+}
+// ============================================================================
+// Levenshtein did-you-mean
+// ============================================================================
+function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++)
+        dp[i][0] = i;
+    for (let j = 0; j <= n; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            if (a[i - 1] === b[j - 1]) {
+                dp[i][j] = dp[i - 1][j - 1];
+            }
+            else {
+                dp[i][j] =
+                    1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+            }
+        }
+    }
+    return dp[m][n];
+}
+function findSuggestion(identifier, validNames) {
+    let best;
+    let bestDist = Infinity;
+    const maxDist = Math.max(2, Math.floor(identifier.length * 0.4));
+    for (const name of validNames) {
+        const dist = levenshtein(identifier, name);
+        if (dist < bestDist && dist <= maxDist) {
+            bestDist = dist;
+            best = name;
+        }
+    }
+    return best;
+}
+// ============================================================================
+// Diagnostic check
+// ============================================================================
+const BUILTIN_IDENTIFIERS = new Set([
+    'params',
+    'query',
+    'path',
+    'fullPath',
+]);
+const LOOP_VARS = new Set([
+    '$index',
+    '$count',
+    '$first',
+    '$last',
+    '$odd',
+    '$even',
+    'item',
+    'key',
+]);
+const LOOP_FORCED_CHECK_SOURCES = new Set([
+    'd-each',
+    'd-virtual-each',
+    'd-virtual-height',
+    'd-virtual-item-height',
+    'd-virtual-overscan',
+]);
+function checkHtmlContent(html, filePath, validIdentifiers, diagnostics) {
+    const ids = extractTemplateIdentifiers(html);
+    const loopRanges = extractLoopRanges(html);
+    for (const id of ids) {
+        if (validIdentifiers.has(id.name))
+            continue;
+        const insideLoop = isInsideLoopRange(id.offset, loopRanges);
+        if (insideLoop) {
+            if (LOOP_VARS.has(id.name))
+                continue;
+            // Loop runtime injects item fields into local scope, so unknown
+            // identifiers may be valid inside loop bodies.
+            if (!LOOP_FORCED_CHECK_SOURCES.has(id.source))
+                continue;
+        }
+        const suggestion = findSuggestion(id.name, [...validIdentifiers]);
+        diagnostics.push({
+            filePath,
+            line: id.line,
+            col: id.col,
+            identifier: id.name,
+            source: id.source,
+            suggestion,
+        });
+    }
+}
+// ============================================================================
+// Route tree helpers
+// ============================================================================
+function collectRouteTsPaths(node, routesDir, out) {
+    for (const file of node.files) {
+        if (file.isHtml)
+            continue;
+        out.push(path.join(routesDir, file.path));
+    }
+    for (const child of node.children) {
+        collectRouteTsPaths(child, routesDir, out);
+    }
+}
+function computeFullPattern(node, parentPattern) {
+    if (!node.segment)
+        return parentPattern || '/';
+    const base = parentPattern === '/' ? '' : parentPattern;
+    return `${base}/${node.routePath}`;
+}
+function traverseAndCheck(node, routesDir, parentPattern, loaderKeysMap, uninferableLoaderPaths, diagnostics) {
+    const currentPattern = computeFullPattern(node, parentPattern);
+    const paramKeys = extractParamKeys(currentPattern);
+    // --- Check page.html ---
+    const pageHtml = findFile(node, 'page', true);
+    const pageTs = findFile(node, 'page', false);
+    if (pageHtml && pageHtml.htmlContent) {
+        const pageTsPath = pageTs ? path.join(routesDir, pageTs.path) : null;
+        const skipPageCheck = pageTsPath && uninferableLoaderPaths.has(pageTsPath);
+        if (!skipPageCheck) {
+            const validIds = new Set(BUILTIN_IDENTIFIERS);
+            for (const k of paramKeys)
+                validIds.add(k);
+            if (pageTs) {
+                const keys = loaderKeysMap.get(path.join(routesDir, pageTs.path));
+                if (keys)
+                    for (const k of keys)
+                        validIds.add(k);
+            }
+            checkHtmlContent(pageHtml.htmlContent, pageHtml.path, validIds, diagnostics);
+        }
+    }
+    // --- Check layout.html ---
+    const layoutHtml = findFile(node, 'layout', true);
+    const layoutTs = findFile(node, 'layout', false);
+    if (layoutHtml && layoutHtml.htmlContent) {
+        const layoutTsPath = layoutTs ? path.join(routesDir, layoutTs.path) : null;
+        const skipLayoutCheck = layoutTsPath && uninferableLoaderPaths.has(layoutTsPath);
+        if (!skipLayoutCheck) {
+            const validIds = new Set(BUILTIN_IDENTIFIERS);
+            for (const k of paramKeys)
+                validIds.add(k);
+            if (layoutTs) {
+                const keys = loaderKeysMap.get(path.join(routesDir, layoutTs.path));
+                if (keys)
+                    for (const k of keys)
+                        validIds.add(k);
+            }
+            checkHtmlContent(layoutHtml.htmlContent, layoutHtml.path, validIds, diagnostics);
+        }
+    }
+    // --- Check error.html, loading.html, not-found.html ---
+    const stateTypes = ['error', 'pending', 'notFound'];
+    for (const type of stateTypes) {
+        const html = findFile(node, type, true);
+        if (!html || !html.htmlContent)
+            continue;
+        const validIds = new Set(BUILTIN_IDENTIFIERS);
+        for (const k of paramKeys)
+            validIds.add(k);
+        if (type === 'error')
+            validIds.add('errorMessage');
+        checkHtmlContent(html.htmlContent, html.path, validIds, diagnostics);
+    }
+    // Recurse into children
+    for (const child of node.children) {
+        traverseAndCheck(child, routesDir, currentPattern, loaderKeysMap, uninferableLoaderPaths, diagnostics);
+    }
+}
+// ============================================================================
+// Main entry point
+// ============================================================================
+export async function runCheck(appDir, options = {}) {
+    const ts = await loadTypeScript();
+    const strictMode = Boolean(options.strict);
+    console.log('');
+    console.log('🔍 Dalila Check');
+    console.log('');
+    const routesDir = path.resolve(appDir);
+    if (!fs.existsSync(routesDir)) {
+        console.error(`❌ App directory not found: ${routesDir}`);
+        return 1;
+    }
+    // 1. Build route tree (reuses routes-generator internals)
+    const tree = await buildRouteTree(routesDir, '', '');
+    const projectRoot = (await findProjectRoot(routesDir)) ?? process.cwd();
+    await injectHtmlPathTemplates(tree, routesDir, projectRoot);
+    // 2. Collect route .ts files, create shared TS Program, infer loader keys by symbols
+    const routeTsPaths = [];
+    collectRouteTsPaths(tree, routesDir, routeTsPaths);
+    const loaderKeysMap = new Map();
+    const uninferableLoaderPaths = new Set();
+    const strictIssues = [];
+    if (routeTsPaths.length > 0) {
+        const tsconfigPath = path.join(projectRoot, 'tsconfig.json');
+        let compilerOptions = {
+            target: ts.ScriptTarget.ES2020,
+            module: ts.ModuleKind.ESNext,
+            moduleResolution: ts.ModuleResolutionKind.NodeJs,
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+        };
+        if (fs.existsSync(tsconfigPath)) {
+            const configFile = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
+            if (configFile.config) {
+                const parsed = ts.parseJsonConfigFileContent(configFile.config, ts.sys, projectRoot);
+                compilerOptions = parsed.options;
+            }
+        }
+        const program = ts.createProgram(routeTsPaths, compilerOptions);
+        const checker = program.getTypeChecker();
+        for (const filePath of routeTsPaths) {
+            const sourceFile = program.getSourceFile(filePath);
+            if (!sourceFile)
+                continue;
+            const loaderSymbol = getLoaderExportSymbol(ts, checker, sourceFile);
+            if (!loaderSymbol)
+                continue;
+            const keys = extractLoaderReturnKeys(ts, checker, loaderSymbol, sourceFile);
+            if (keys) {
+                loaderKeysMap.set(filePath, keys);
+            }
+            else {
+                uninferableLoaderPaths.add(filePath);
+                if (strictMode) {
+                    strictIssues.push(`${path.relative(process.cwd(), filePath)} exports "loader", but its return type could not be inferred`);
+                }
+            }
+        }
+    }
+    // 3. Traverse tree and check all HTML templates
+    const diagnostics = [];
+    traverseAndCheck(tree, routesDir, '/', loaderKeysMap, uninferableLoaderPaths, diagnostics);
+    // 4. Report results
+    if (strictIssues.length === 0 && diagnostics.length === 0) {
+        console.log('✅ No errors found');
+        console.log('');
+        return 0;
+    }
+    if (strictIssues.length > 0) {
+        console.log('  Strict mode');
+        for (const issue of strictIssues) {
+            console.log(`    ❌ ${issue}`);
+        }
+        console.log('');
+    }
+    // Group by file
+    const grouped = new Map();
+    for (const d of diagnostics) {
+        const list = grouped.get(d.filePath) ?? [];
+        list.push(d);
+        grouped.set(d.filePath, list);
+    }
+    for (const [file, diags] of grouped) {
+        console.log(`  ${file}`);
+        for (const d of diags) {
+            const loc = `${d.line}:${d.col}`;
+            let msg = `"${d.identifier}" is not defined in template context (${d.source})`;
+            if (d.suggestion) {
+                msg += `. Did you mean "${d.suggestion}"?`;
+            }
+            console.log(`    ${loc.padEnd(8)} ❌ ${msg}`);
+        }
+        console.log('');
+    }
+    const totalErrors = diagnostics.length + strictIssues.length;
+    const fileCount = grouped.size + strictIssues.length;
+    console.log(`❌ Found ${totalErrors} error${totalErrors === 1 ? '' : 's'} in ${fileCount} file${fileCount === 1 ? '' : 's'}`);
+    console.log('');
+    return 1;
+}

package/dist/cli/index.js

@@ -16,15 +16,18 @@ Usage:
   dalila routes init                  Initialize app and generate routes outputs
   dalila routes watch [options]       Watch routes and regenerate outputs on changes
   dalila routes --help                Show routes command help
+  dalila check [path] [--strict]     Static analysis of HTML templates against loaders
   dalila help                         Show this help message
 
 Options:
   --output <path>     Output file (default: ./routes.generated.ts)
 
 Examples:
-  dalila routes generate
-  dalila routes generate --output src/routes.generated.ts
-  dalila routes init
+  npx dalila routes generate
+  npx dalila routes generate --output src/routes.generated.ts
+  npx dalila routes init
+  npx dalila check
+  npx dalila check src/app --strict
 `);
 }
 function showRoutesHelp() {
@@ -41,10 +44,33 @@ Options:
   --output <path>     Output file (default: ./routes.generated.ts)
 
 Examples:
-  dalila routes generate
-  dalila routes generate --output src/routes.generated.ts
-  dalila routes watch
-  dalila routes init
+  npx dalila routes generate
+  npx dalila routes generate --output src/routes.generated.ts
+  npx dalila routes watch
+  npx dalila routes init
+`);
+}
+function showCheckHelp() {
+    console.log(`
+Dalila CLI - Check
+
+Usage:
+  dalila check [path] [options]     Static analysis of HTML templates
+
+Validates that identifiers used in HTML templates ({expr}, d-* directives)
+match the return type of the corresponding loader() in TypeScript.
+
+Arguments:
+  [path]          App directory to check (default: src/app)
+
+Options:
+  --strict        Fail when exported loader return keys cannot be inferred
+  --help, -h      Show this help message
+
+Examples:
+  npx dalila check
+  npx dalila check src/app
+  npx dalila check --strict
 `);
 }
 function hasHelpFlag(list) {
@@ -331,6 +357,22 @@ async function main() {
             process.exit(1);
         }
     }
+    else if (command === 'check') {
+        const checkArgs = args.slice(1);
+        if (hasHelpFlag(checkArgs)) {
+            showCheckHelp();
+        }
+        else {
+            const strict = checkArgs.includes('--strict');
+            const positional = checkArgs.filter(a => !a.startsWith('--'));
+            const appDir = positional[0]
+                ? path.resolve(positional[0])
+                : resolveDefaultAppDir(process.cwd());
+            const { runCheck } = await import('./check.js');
+            const exitCode = await runCheck(appDir, { strict });
+            process.exit(exitCode);
+        }
+    }
     else if (command === '--help' || command === '-h') {
         showHelp();
     }

package/dist/cli/routes-generator.d.ts

@@ -1,3 +1,28 @@
+export type RouteFileType = 'middleware' | 'layout' | 'page' | 'error' | 'pending' | 'notFound';
+export interface RouteFile {
+    path: string;
+    type: RouteFileType;
+    importName: string;
+    isHtml: boolean;
+    htmlContent?: string;
+    htmlPath?: string;
+    sourceContent?: string;
+    namedExports?: string[];
+    tags?: string[];
+    lazy?: boolean;
+}
+export interface RouteNode {
+    fsPath: string;
+    segment: string;
+    routePath: string;
+    files: RouteFile[];
+    children: RouteNode[];
+}
+export declare function extractParamKeys(routePattern: string): string[];
+export declare function injectHtmlPathTemplates(node: RouteNode, routesDir: string, projectRoot: string): Promise<void>;
+export declare function findProjectRoot(startDir: string): Promise<string | null>;
+export declare function findFile(node: RouteNode, type: RouteFileType, isHtml?: boolean): RouteFile | undefined;
+export declare function buildRouteTree(routesDir: string, currentPath?: string, currentSegment?: string): Promise<RouteNode>;
 export declare function collectHtmlPathDependencyDirs(routesDir: string): string[];
 /**
  * Generate route files from the app directory.

package/dist/cli/routes-generator.js

@@ -128,7 +128,7 @@ function parseRouteParamSegment(segment) {
     }
     return { key: raw, isCatchAll: false, isOptionalCatchAll: false };
 }
-function extractParamKeys(routePattern) {
+export function extractParamKeys(routePattern) {
     const keys = [];
     const segments = normalizeRoutePath(routePattern).split('/').filter(Boolean);
     for (const segment of segments) {
@@ -257,7 +257,7 @@ function resolveHtmlPath(htmlPath, routesDir, filePath, projectRoot) {
     }
     return path.resolve(routeFileDir, htmlPath);
 }
-async function injectHtmlPathTemplates(node, routesDir, projectRoot) {
+export async function injectHtmlPathTemplates(node, routesDir, projectRoot) {
     const syntheticHtmlFiles = [];
     for (const file of node.files) {
         if (file.isHtml || !file.htmlPath)
@@ -299,7 +299,7 @@ const DEFAULT_ROUTE_TAG_POLICY = {
     ],
     priority: ['auth', 'public']
 };
-async function findProjectRoot(startDir) {
+export async function findProjectRoot(startDir) {
     let current = path.resolve(startDir);
     while (true) {
         if (await pathExists(path.join(current, 'package.json'))) {
@@ -409,7 +409,7 @@ function validateManifestTags(entries, policy) {
         }
     }
 }
-function findFile(node, type, isHtml) {
+export function findFile(node, type, isHtml) {
     return node.files.find((file) => {
         if (file.type !== type)
             return false;
@@ -591,7 +591,7 @@ function buildRouteTreeSync(routesDir, currentPath = '', currentSegment = '') {
     }
     return node;
 }
-async function buildRouteTree(routesDir, currentPath = '', currentSegment = '') {
+export async function buildRouteTree(routesDir, currentPath = '', currentSegment = '') {
     const node = {
         fsPath: currentPath.replace(/\\/g, '/'),
         segment: currentSegment,

package/dist/router/route-tables.d.ts

@@ -40,19 +40,19 @@ export type RouteMiddlewareResolver = RouteMiddleware[] | ((ctx: RouteCtx) => Ro
  * data loading, state views, children, guards, middleware, redirects,
  * and params/query validation.
  */
-export interface RouteTable {
+export interface RouteTable<T = any> {
     path: string;
     id?: string;
     score?: number;
     paramKeys?: string[];
     tags?: string[];
-    view?: (ctx: RouteCtx, data: any) => Node | DocumentFragment | Node[];
-    layout?: (ctx: RouteCtx, child: Node | DocumentFragment | Node[], data: any) => Node | DocumentFragment | Node[];
-    loader?: (ctx: RouteCtx) => Promise<any>;
-    preload?: (ctx: RouteCtx) => Promise<any>;
+    view?: (ctx: RouteCtx, data: T) => Node | DocumentFragment | Node[];
+    layout?: (ctx: RouteCtx, child: Node | DocumentFragment | Node[], data: T) => Node | DocumentFragment | Node[];
+    loader?: (ctx: RouteCtx) => Promise<T>;
+    preload?: (ctx: RouteCtx) => Promise<T>;
     onMount?: (root: HTMLElement) => void;
     pending?: (ctx: RouteCtx) => Node | DocumentFragment | Node[];
-    error?: (ctx: RouteCtx, error: unknown, data?: any) => Node | DocumentFragment | Node[];
+    error?: (ctx: RouteCtx, error: unknown, data?: T) => Node | DocumentFragment | Node[];
     notFound?: (ctx: RouteCtx) => Node | DocumentFragment | Node[];
     children?: RouteTable[];
     middleware?: RouteMiddlewareResolver;
@@ -60,6 +60,23 @@ export interface RouteTable {
     redirect?: string | ((ctx: RouteCtx) => RouteRedirectResult);
     validation?: RouteValidationResolver;
 }
+/**
+ * Helper to define a single route with full type inference between
+ * `loader` return type and the `view` / `layout` / `error` `data` parameter.
+ *
+ * @example
+ * ```ts
+ * const route = defineRoute({
+ *   path: '/users',
+ *   loader: async () => ({ users: await fetchUsers() }),
+ *   view: (ctx, data) => {
+ *     // data is inferred as { users: User[] }
+ *     return fromHtml(tpl, { data });
+ *   },
+ * });
+ * ```
+ */
+export declare function defineRoute<T = any>(route: RouteTable<T>): RouteTable<T>;
 /** Immutable snapshot of the current navigation state. */
 export interface RouteState {
     path: string;

package/dist/router/route-tables.js

@@ -1,3 +1,22 @@
+/**
+ * Helper to define a single route with full type inference between
+ * `loader` return type and the `view` / `layout` / `error` `data` parameter.
+ *
+ * @example
+ * ```ts
+ * const route = defineRoute({
+ *   path: '/users',
+ *   loader: async () => ({ users: await fetchUsers() }),
+ *   view: (ctx, data) => {
+ *     // data is inferred as { users: User[] }
+ *     return fromHtml(tpl, { data });
+ *   },
+ * });
+ * ```
+ */
+export function defineRoute(route) {
+    return route;
+}
 /** Normalize a path: ensure leading slash, collapse duplicates, strip trailing slash. */
 export function normalizePath(path) {
     if (!path)

package/dist/runtime/bind.d.ts

@@ -41,7 +41,19 @@ export interface BindOptions {
 export interface BindContext {
     [key: string]: unknown;
 }
+/**
+ * Convenience alias: any object whose values are `unknown`.
+ * Use the generic parameter on `bind<T>()` / `autoBind<T>()` / `fromHtml<T>()`
+ * to preserve the concrete type at call sites while still satisfying internal
+ * look-ups that index by string key.
+ */
+export type BindData<T extends Record<string, unknown> = Record<string, unknown>> = T;
 export type DisposeFunction = () => void;
+export interface BindHandle {
+    (): void;
+    getRef(name: string): Element | null;
+    getRefs(): Readonly<Record<string, Element>>;
+}
 /**
  * Bind a DOM tree to a reactive context.
  *
@@ -65,7 +77,7 @@ export type DisposeFunction = () => void;
  * dispose();
  * ```
  */
-export declare function bind(root: Element, ctx: BindContext, options?: BindOptions): DisposeFunction;
+export declare function bind<T extends Record<string, unknown> = BindContext>(root: Element, ctx: T, options?: BindOptions): BindHandle;
 /**
  * Automatically bind when DOM is ready.
  * Useful for simple pages without a build step.
@@ -78,4 +90,4 @@ export declare function bind(root: Element, ctx: BindContext, options?: BindOpti
  * </script>
  * ```
  */
-export declare function autoBind(selector: string, ctx: BindContext, options?: BindOptions): Promise<DisposeFunction>;
+export declare function autoBind<T extends Record<string, unknown> = BindContext>(selector: string, ctx: T, options?: BindOptions): Promise<BindHandle>;

package/dist/runtime/bind.js

@@ -2445,6 +2445,24 @@ function bindArrayOperations(container, fieldArray, cleanups) {
     }
 }
 // ============================================================================
+// d-ref — declarative element references
+// ============================================================================
+function bindRef(root, refs) {
+    const elements = qsaIncludingRoot(root, '[d-ref]');
+    for (const el of elements) {
+        const name = el.getAttribute('d-ref');
+        if (!name || !name.trim()) {
+            warn('d-ref: empty ref name ignored');
+            continue;
+        }
+        const trimmed = name.trim();
+        if (refs.has(trimmed)) {
+            warn(`d-ref: duplicate ref name "${trimmed}" in the same scope`);
+        }
+        refs.set(trimmed, el);
+    }
+}
+// ============================================================================
 // Main bind() Function
 // ============================================================================
 /**
@@ -2484,6 +2502,7 @@ export function bind(root, ctx, options = {}) {
     // Create a scope for this template binding
     const templateScope = createScope();
     const cleanups = [];
+    const refs = new Map();
     linkScopeToDom(templateScope, root, describeBindRoot(root));
     // Run all bindings within the template scope
     withScope(templateScope, () => {
@@ -2495,24 +2514,26 @@ export function bind(root, ctx, options = {}) {
         bindVirtualEach(root, ctx, cleanups);
         // 4. d-each — must run early: removes templates before TreeWalker visits them
         bindEach(root, ctx, cleanups);
-        // 5. Text interpolation (template plan cache + lazy parser fallback)
+        // 5. d-ref — collect element references (after d-each removes templates)
+        bindRef(root, refs);
+        // 6. Text interpolation (template plan cache + lazy parser fallback)
         bindTextInterpolation(root, ctx, rawTextSelectors, templatePlanCacheConfig, benchSession);
-        // 6. d-attr bindings
+        // 7. d-attr bindings
         bindAttrs(root, ctx, cleanups);
-        // 7. d-html bindings
+        // 8. d-html bindings
         bindHtml(root, ctx, cleanups);
-        // 8. Form fields — register fields with form instances
+        // 9. Form fields — register fields with form instances
         bindField(root, ctx, cleanups);
-        // 9. Event bindings
+        // 10. Event bindings
         bindEvents(root, ctx, events, cleanups);
-        // 10. d-when directive
+        // 11. d-when directive
         bindWhen(root, ctx, cleanups);
-        // 11. d-match directive
+        // 12. d-match directive
         bindMatch(root, ctx, cleanups);
-        // 12. Form error displays — BEFORE d-if to bind errors in conditionally rendered sections
+        // 13. Form error displays — BEFORE d-if to bind errors in conditionally rendered sections
         bindError(root, ctx, cleanups);
         bindFormError(root, ctx, cleanups);
-        // 13. d-if — must run last: elements are fully bound before conditional removal
+        // 14. d-if — must run last: elements are fully bound before conditional removal
         bindIf(root, ctx, cleanups);
     });
     // Bindings complete: remove loading state and mark as ready.
@@ -2524,8 +2545,8 @@ export function bind(root, ctx, options = {}) {
         });
     }
     flushBindBenchSession(benchSession);
-    // Return dispose function
-    return () => {
+    // Return BindHandle (callable dispose + ref accessors)
+    const dispose = () => {
         // Run manual cleanups (event listeners)
         for (const cleanup of cleanups) {
             if (typeof cleanup === 'function') {
@@ -2540,6 +2561,7 @@ export function bind(root, ctx, options = {}) {
             }
         }
         cleanups.length = 0;
+        refs.clear();
         // Dispose template scope (stops all effects)
         try {
             templateScope.dispose();
@@ -2550,6 +2572,15 @@ export function bind(root, ctx, options = {}) {
             }
         }
     };
+    const handle = Object.assign(dispose, {
+        getRef(name) {
+            return refs.get(name) ?? null;
+        },
+        getRefs() {
+            return Object.freeze(Object.fromEntries(refs));
+        },
+    });
+    return handle;
 }
 // ============================================================================
 // Convenience: Auto-bind on DOMContentLoaded

package/dist/runtime/fromHtml.d.ts

@@ -9,9 +9,9 @@
  * @module dalila/runtime
  */
 import type { Scope } from '../core/scope.js';
-export interface FromHtmlOptions {
+export interface FromHtmlOptions<T extends Record<string, unknown> = Record<string, unknown>> {
     /** Bind context — keys map to {placeholder} tokens in the HTML */
-    data?: Record<string, unknown>;
+    data?: T;
     /** Child nodes to inject into [data-slot="children"] */
     children?: Node | DocumentFragment | Node[];
     /** Route scope — registers bind cleanup automatically */
@@ -32,4 +32,5 @@ export interface FromHtmlOptions {
  * const el = fromHtml('<div><div data-slot="children"></div></div>', { children });
  * ```
  */
+export declare function fromHtml<T extends Record<string, unknown>>(html: string, options: FromHtmlOptions<T>): HTMLElement;
 export declare function fromHtml(html: string, options?: FromHtmlOptions): HTMLElement;

package/dist/runtime/fromHtml.js

@@ -9,21 +9,6 @@
  * @module dalila/runtime
  */
 import { bind } from './bind.js';
-/**
- * Parse an HTML string into a bound DOM element.
- *
- * @example
- * ```ts
- * // Static HTML
- * const el = fromHtml('<div><h1>Hello</h1></div>');
- *
- * // With data binding
- * const el = fromHtml('<div>{name}</div>', { data: { name: 'Dalila' } });
- *
- * // Layout with children slot
- * const el = fromHtml('<div><div data-slot="children"></div></div>', { children });
- * ```
- */
 export function fromHtml(html, options = {}) {
     const { data, children, scope } = options;
     const template = document.createElement('template');

package/dist/runtime/index.d.ts

@@ -7,6 +7,6 @@
  * @module dalila/runtime
  */
 export { bind, autoBind } from './bind.js';
-export type { BindOptions, BindContext, DisposeFunction } from './bind.js';
+export type { BindOptions, BindContext, BindData, DisposeFunction, BindHandle } from './bind.js';
 export { fromHtml } from './fromHtml.js';
 export type { FromHtmlOptions } from './fromHtml.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dalila",
-  "version": "1.9.2",
+  "version": "1.9.3",
   "description": "DOM-first reactive framework based on signals",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -100,7 +100,7 @@
     "build": "tsc && node scripts/ensure-cli-executable.cjs",
     "dev": "tsc --watch",
     "serve": "node scripts/dev-server.cjs",
-    "test": "npm run build && node --test",
+    "test": "npm run build && node --test --test-concurrency=1 test/*.test.js",
     "test:e2e": "npm run build && playwright test",
     "test:watch": "jest --watch",
     "clean": "rm -rf dist",