@heshammesalam/heshjs 0.0.0-stage → 0.1.0

package/src/compiler/index.ts

@@ -0,0 +1,231 @@
+import ts from 'typescript';
+import { parse, tokenize, HeshError, type Expression, type Element, type Module } from '../parser/index.js';
+
+export interface CompileOptions { filename?: string; development?: boolean; runtime?: string; reactivity?: string }
+export interface Binding { view: string; start: number; end: number; dependencies: string[]; kind: string }
+export interface ViewIR { name: string; exported: boolean; default: boolean; instructions: string[] }
+export interface ModuleIR { prelude: string[]; views: ViewIR[]; bindings: Binding[] }
+export interface Result { code: string; css: string; metadata: Binding[]; ast: Module; ir: ModuleIR }
+const printer = ts.createPrinter();
+const f = ts.factory;
+
+export function compile(source: string, options: CompileOptions = {}): Result {
+  const ast = parse(source, options.filename);
+  const metadata: Binding[] = [];
+  const fail = (message: string, offset: number): never => { throw new HeshError(message, source, offset, ast.filename); };
+  const names = new Set<string>();
+  let defaults = 0;
+  const imported = new Set<string>();
+  const addImport = (name: string, offset: number): void => {
+    if (name.startsWith('__h')) fail('Identifiers beginning __h are reserved', offset);
+    if (imported.has(name)) fail(`Duplicate import binding ${name}`, offset);
+    imported.add(name);
+  };
+  for (const item of ast.imports) {
+    const diagnostics = ts.transpileModule(item.source, { fileName: 'imports.js', reportDiagnostics: true, compilerOptions: { allowJs: true, module: ts.ModuleKind.ESNext } }).diagnostics;
+    if (diagnostics?.length) fail(ts.flattenDiagnosticMessageText(diagnostics[0]!.messageText, '\n'), item.start);
+    const parsed = ts.createSourceFile('imports.js', item.source, ts.ScriptTarget.Latest, true, ts.ScriptKind.JS);
+    const statement = parsed.statements[0];
+    if (!statement || !ts.isImportDeclaration(statement)) fail('Expected ESM import', item.start);
+    const clause = (statement as ts.ImportDeclaration).importClause;
+    if (clause?.name) addImport(clause.name.text, item.start);
+    const bindings = clause?.namedBindings;
+    if (bindings && ts.isNamedImports(bindings)) bindings.elements.forEach(e => addImport(e.name.text, item.start));
+    else if (bindings) addImport(bindings.name.text, item.start);
+  }
+  for (const view of ast.views) {
+    if (!/^[A-Z]/.test(view.name)) fail('View names must begin with an uppercase letter', view.start);
+    if (names.has(view.name) || imported.has(view.name)) fail(`Duplicate component ${view.name}`, view.start);
+    names.add(view.name);
+    if (view.default && ++defaults > 1) fail('Only one default view is allowed', view.start);
+  }
+  const prelude = [
+    `import { signal as __hSignal } from ${JSON.stringify(options.reactivity ?? '@heshammesalam/heshjs/reactivity')};`,
+    `import * as __hDOM from ${JSON.stringify(options.runtime ?? '@heshammesalam/heshjs/dom')};`,
+    ...ast.imports.map(i => i.source),
+    'const __hUpdate = (s, delta, post) => { const value = s.get(); const old = typeof value === "bigint" ? value : +value; const next = typeof old === "bigint" ? old + BigInt(delta) : old + delta; s.set(next); return post ? old : next; };'
+  ];
+  const views: ViewIR[] = [];
+  for (const view of ast.views) {
+    const output: string[] = [];
+    const states = new Set<string>(), constants = new Set<string>();
+    for (const node of view.body) if (node.kind !== 'element') {
+      if (states.has(node.name) || constants.has(node.name) || imported.has(node.name) || names.has(node.name)) fail(`Duplicate binding ${node.name}`, node.start);
+      (node.kind === 'state' ? states : constants).add(node.name);
+    }
+    let serial = 0;
+    const available = new Set<string>();
+    const transform = (expression: Expression, handler = false, async = false): string => {
+      const declarations = [...states, ...constants].map(name => `${constants.has(name) ? 'const' : 'let'} ${name} = undefined;`).join('\n');
+      const prefix = `${ast.imports.map(i => i.source).join('\n')}\n${[...names].map(n => `function ${n}() {}`).join('\n')}\nfunction __hContext() {\n${declarations}\n${async ? 'async ' : ''}function __hExpression(${handler ? 'event' : ''}) {\n${handler ? '' : 'return ('}`;
+      const text = prefix + expression.source + (handler ? '' : ');') + '\n}\n}';
+      const filename = '/__hesh_expression__.js';
+      const settings: ts.CompilerOptions = { allowJs: true, checkJs: true, target: ts.ScriptTarget.ESNext, module: ts.ModuleKind.ESNext, noEmit: true };
+      const host = ts.createCompilerHost(settings);
+      const original = host.getSourceFile.bind(host);
+      host.getSourceFile = (name, languageVersion, onError, shouldCreate) => name === filename ? ts.createSourceFile(name, text, languageVersion, true, ts.ScriptKind.JS) : original(name, languageVersion, onError, shouldCreate);
+      const program = ts.createProgram([filename], settings, host);
+      const file = program.getSourceFile(filename)!;
+      const diagnostics = program.getSyntacticDiagnostics(file);
+      if (diagnostics.length) {
+        const d = diagnostics[0]!;
+        fail(ts.flattenDiagnosticMessageText(d.messageText, '\n'), expression.start + Math.max(0, (d.start ?? prefix.length) - prefix.length));
+      }
+      const checker = program.getTypeChecker();
+      const context = file.statements.find(n => ts.isFunctionDeclaration(n) && n.name?.text === '__hContext') as ts.FunctionDeclaration;
+      const symbols = new Map<ts.Symbol, string>();
+      for (const stmt of context.body!.statements) if (ts.isVariableStatement(stmt)) {
+        const name = stmt.declarationList.declarations[0]!.name as ts.Identifier;
+        symbols.set(checker.getSymbolAtLocation(name)!, name.text);
+      }
+      const fn = context.body!.statements.at(-1) as ts.FunctionDeclaration;
+      const dependencies = new Set<string>();
+      const stateName = (node: ts.Node): string | undefined => {
+        if (!ts.isIdentifier(node)) return;
+        const symbol = checker.getSymbolAtLocation(node);
+        const name = symbol ? symbols.get(symbol) : undefined;
+        if (name && !handler && !available.has(name)) fail(`Binding ${name} is used before initialization`, expression.start);
+        return name;
+      };
+      const read = (name: string) => f.createCallExpression(f.createPropertyAccessExpression(f.createIdentifier(name), 'get'), undefined, []);
+      const write = (name: string, value: ts.Expression) => f.createCallExpression(f.createPropertyAccessExpression(f.createIdentifier(name), 'set'), undefined, [value]);
+      const result = ts.transform(fn.body!, [context => {
+        const visit: ts.Visitor = node => {
+          if (ts.isIdentifier(node) && node.text.startsWith('__h')) fail('Identifiers beginning __h are reserved', expression.start + Math.max(0, node.getStart(file) - prefix.length));
+          if ((ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) && [ts.SyntaxKind.PlusPlusToken, ts.SyntaxKind.MinusMinusToken].includes(node.operator)) {
+            const name = stateName(node.operand);
+            if (name) {
+              dependencies.add(name);
+              if (constants.has(name)) fail(`Cannot assign constant ${name}`, expression.start);
+              const delta = node.operator === ts.SyntaxKind.PlusPlusToken ? f.createNumericLiteral(1) : f.createPrefixUnaryExpression(ts.SyntaxKind.MinusToken, f.createNumericLiteral(1));
+              return f.createCallExpression(f.createIdentifier('__hUpdate'), undefined, [f.createIdentifier(name), delta, node.kind === ts.SyntaxKind.PostfixUnaryExpression ? f.createTrue() : f.createFalse()]);
+            }
+          }
+          if (ts.isBinaryExpression(node) && node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment && node.operatorToken.kind <= ts.SyntaxKind.LastAssignment) {
+            if (ts.isArrayLiteralExpression(node.left) || ts.isObjectLiteralExpression(node.left)) {
+              const checkTarget = (target: ts.Node): void => {
+                const name = stateName(target);
+                if (name) fail('Destructuring assignments to component bindings are not supported', expression.start);
+                ts.forEachChild(target, checkTarget);
+              };
+              checkTarget(node.left);
+            }
+            const name = stateName(node.left);
+            if (name) {
+              dependencies.add(name);
+              if (constants.has(name)) fail(`Cannot assign constant ${name}`, expression.start);
+              const right = ts.visitNode(node.right, visit) as ts.Expression;
+              if (node.operatorToken.kind === ts.SyntaxKind.EqualsToken) return write(name, right);
+              const operators: Partial<Record<ts.SyntaxKind, ts.BinaryOperator>> = {
+                [ts.SyntaxKind.PlusEqualsToken]: ts.SyntaxKind.PlusToken, [ts.SyntaxKind.MinusEqualsToken]: ts.SyntaxKind.MinusToken,
+                [ts.SyntaxKind.AsteriskEqualsToken]: ts.SyntaxKind.AsteriskToken, [ts.SyntaxKind.SlashEqualsToken]: ts.SyntaxKind.SlashToken,
+                [ts.SyntaxKind.PercentEqualsToken]: ts.SyntaxKind.PercentToken, [ts.SyntaxKind.AsteriskAsteriskEqualsToken]: ts.SyntaxKind.AsteriskAsteriskToken,
+                [ts.SyntaxKind.AmpersandEqualsToken]: ts.SyntaxKind.AmpersandToken, [ts.SyntaxKind.BarEqualsToken]: ts.SyntaxKind.BarToken,
+                [ts.SyntaxKind.CaretEqualsToken]: ts.SyntaxKind.CaretToken, [ts.SyntaxKind.LessThanLessThanEqualsToken]: ts.SyntaxKind.LessThanLessThanToken,
+                [ts.SyntaxKind.GreaterThanGreaterThanEqualsToken]: ts.SyntaxKind.GreaterThanGreaterThanToken, [ts.SyntaxKind.GreaterThanGreaterThanGreaterThanEqualsToken]: ts.SyntaxKind.GreaterThanGreaterThanGreaterThanToken
+              };
+              const op = operators[node.operatorToken.kind];
+              if (!op) fail('Logical assignment to state is not supported yet', expression.start);
+              return write(name, f.createBinaryExpression(read(name), op!, right));
+            }
+          }
+          if (ts.isShorthandPropertyAssignment(node)) {
+            const symbol = checker.getShorthandAssignmentValueSymbol(node);
+            const name = symbol && symbols.get(symbol);
+            if (name && !handler && !available.has(name)) fail(`Binding ${name} is used before initialization`, expression.start);
+            if (name && states.has(name)) { dependencies.add(name); return f.createPropertyAssignment(node.name.text, read(name)); }
+          }
+          if (ts.isIdentifier(node)) {
+            const name = stateName(node);
+            if (name && !handler && !available.has(name)) fail(`Binding ${name} is used before initialization`, expression.start);
+            if (name && states.has(name)) { dependencies.add(name); return read(name); }
+          }
+          if ((ts.isForOfStatement(node) || ts.isForInStatement(node)) && stateName(node.initializer)) fail('Use a local loop variable, then assign state in the loop body', expression.start);
+          return ts.visitEachChild(node, visit, context);
+        };
+        return node => ts.visitNode(node, visit) as ts.Block;
+      }]);
+      // Report unresolved names while leaving module resolution and imported types to Vite/tsc.
+      for (const d of program.getSemanticDiagnostics(file)) if ((d.code < 2000 || [2304, 2552, 2588].includes(d.code)) && (d.start ?? 0) >= prefix.length && (d.start ?? 0) < prefix.length + expression.source.length) {
+        fail(ts.flattenDiagnosticMessageText(d.messageText, '\n'), expression.start + d.start! - prefix.length);
+      }
+      const body = result.transformed[0] as ts.Block;
+      metadata.push({ view: view.name, start: expression.start, end: expression.end, dependencies: [...dependencies].sort(), kind: handler ? 'event' : 'expression' });
+      let rendered: string;
+      if (handler) rendered = printer.printNode(ts.EmitHint.Unspecified, body, file);
+      else rendered = printer.printNode(ts.EmitHint.Expression, (body.statements[0] as ts.ReturnStatement).expression!, file);
+      result.dispose();
+      return rendered;
+    };
+    const value = (expr: Expression): string => {
+      if (!expr.source.startsWith('"')) return transform(expr);
+      const tokens = tokenize(expr.source);
+      if (tokens.length !== 1 || tokens[0]!.kind !== ts.SyntaxKind.StringLiteral) return transform(expr);
+      const raw = expr.source.slice(1, -1);
+      const parts: string[] = [];
+      let literal = '', i = 0;
+      const emit = () => { if (literal) { parts.push(JSON.stringify(literal)); literal = ''; } };
+      while (i < raw.length) {
+        if (raw[i] === '\\') {
+          const next = raw[++i];
+          const escapes: Record<string, string> = { n: '\n', r: '\r', t: '\t', b: '\b', f: '\f', v: '\v', '0': '\0' };
+          if (next === 'u' || next === 'x') fail('Use single quotes for Unicode/hex escapes in literal strings', expr.start + i);
+          literal += escapes[next ?? ''] ?? next ?? ''; i++; continue;
+        }
+        if (raw[i] !== '{') { literal += raw[i++]; continue; }
+        emit(); const start = ++i;
+        const nested = tokenize(raw.slice(start)); let depth = 1, end = -1;
+        for (const token of nested) { if (token.text === '{') depth++; if (token.text === '}' && --depth === 0) { end = start + token.start; break; } }
+        if (end < 0) fail('Unterminated text interpolation', expr.start + start);
+        parts.push(`String(${transform({ source: raw.slice(start, end), start: expr.start + 1 + start, end: expr.start + 1 + end })} ?? "")`);
+        i = end + 1;
+      }
+      emit(); return parts.length ? parts.join(' + ') : '""';
+    };
+    const emit = (node: Element, parent: string): void => {
+      if (/^[A-Z]/.test(node.name)) {
+        if (!names.has(node.name) && !imported.has(node.name)) fail(`Unknown component ${node.name}`, node.start);
+        if (node.value || node.handler || node.children.length) fail('Component props, event blocks and slots are not supported in Milestone 1', node.start);
+        output.push(`__hDOM.component(${parent}, ${node.name});`); return;
+      }
+      const id = `__hNode${serial++}`;
+      output.push(`const ${id} = __hDOM.element(${parent}, ${JSON.stringify(node.name)});`);
+      if (node.value) {
+        if (node.name === 'input') {
+          if (!states.has(node.value.source.trim()) || !available.has(node.value.source.trim())) fail('input requires an initialized state identifier', node.value.start);
+          output.push(`__hDOM.input(${id}, ${node.value.source});`);
+        } else if (node.name === 'image' || node.name === 'img') output.push(`__hDOM.attribute(${id}, "src", () => ${value(node.value)});`);
+        else output.push(`__hDOM.text(${id}, () => ${value(node.value)});`);
+      }
+      if (node.handler) output.push(`__hDOM.listen(${id}, "click", ${node.async ? 'async ' : ''}(event) => ${transform(node.handler, true, node.async)});`);
+      node.children.forEach(child => emit(child, id));
+    };
+    for (const node of view.body) {
+      if (node.kind === 'element') emit(node, '__hParent');
+      else { output.push(`const ${node.name} = ${node.kind === 'state' ? '__hSignal(' : ''}${transform(node.value)}${node.kind === 'state' ? ')' : ''};`); available.add(node.name); }
+    }
+    views.push({ name: view.name, exported: view.exported, default: view.default, instructions: output });
+  }
+  const ir: ModuleIR = { prelude, views, bindings: options.development === false ? [] : metadata };
+  const output = [...ir.prelude, ...ir.views.flatMap(view => [
+    `${view.exported ? 'export ' : ''}${view.default ? 'default ' : ''}function ${view.name}(__hParent) {`,
+    ...view.instructions.map(instruction => instruction.split('\n').map(line => `  ${line}`).join('\n')),
+    '}'
+  ])];
+  if (options.development !== false) output.push(`export const __hesh = ${JSON.stringify(metadata)};`);
+  return { code: output.join('\n'), css: '', metadata: options.development === false ? [] : metadata, ast, ir };
+}
+
+export function createCompiler() {
+  const cache = new Map<string, Result>();
+  return {
+    compile(source: string, options: CompileOptions = {}) {
+      const key = JSON.stringify([source, options]);
+      let result = cache.get(key);
+      if (!result) { result = compile(source, options); cache.set(key, result); }
+      return result;
+    },
+    clear() { cache.clear(); }
+  };
+}
+

package/src/dom/index.ts

@@ -0,0 +1,67 @@
+import { effect, onCleanup, scope, batch, type Signal, type Disposer } from '../reactivity/index.js';
+export type Component = (parent: Node) => void;
+export interface MountOptions { onError?: (error: unknown) => void }
+let errorHandler: (error: unknown) => void = error => console.error(error);
+const aliases: Record<string, string> = { text: 'span', card: 'div', row: 'div', stack: 'div', grid: 'div', image: 'img', link: 'a' };
+
+export function mount(component: Component, parent: Node, options: MountOptions = {}): Disposer {
+  const previous = errorHandler;
+  errorHandler = options.onError ?? previous;
+  try { return scope(() => component(parent)).dispose; }
+  finally { errorHandler = previous; }
+}
+
+export function element(parent: Node, name: string): HTMLElement {
+  const node = parent.ownerDocument!.createElement(aliases[name] ?? name);
+  parent.appendChild(node);
+  onCleanup(() => node.remove());
+  return node;
+}
+
+export function text(parent: Node, read: () => unknown): void {
+  const node = parent.ownerDocument!.createTextNode('');
+  parent.appendChild(node);
+  onCleanup(() => node.remove());
+  effect(() => { node.data = String(read() ?? ''); });
+}
+
+function safeURL(value: string): string {
+  // Parse like a browser, including embedded ASCII tabs/newlines.
+  const normalized = value.replace(/[\u0000-\u0020]/g, '');
+  const scheme = /^([a-z][a-z\d+.-]*):/i.exec(normalized)?.[1]?.toLowerCase();
+  if (scheme && !['http', 'https', 'mailto', 'tel'].includes(scheme)) {
+    throw new Error(`Unsafe URL scheme: ${scheme}`);
+  }
+  return value;
+}
+
+export function attribute(node: HTMLElement, name: string, read: () => unknown): void {
+  if (/^on/i.test(name) || ['innerhtml', 'outerhtml', 'srcdoc'].includes(name.toLowerCase())) throw new Error(`Unsafe attribute: ${name}`);
+  effect(() => {
+    const value = read();
+    if (value == null || value === false) node.removeAttribute(name);
+    else {
+      const rendered = value === true ? '' : String(value);
+      node.setAttribute(name, ['href', 'src', 'action', 'formaction', 'poster', 'xlink:href'].includes(name.toLowerCase()) ? safeURL(rendered) : rendered);
+    }
+  });
+}
+
+export function listen(node: HTMLElement, name: string, handler: (event: Event) => unknown): void {
+  const report = errorHandler;
+  const listener = (event: Event) => {
+    try { Promise.resolve(batch(() => handler(event))).catch(report); }
+    catch (error) { report(error); }
+  };
+  node.addEventListener(name, listener);
+  onCleanup(() => node.removeEventListener(name, listener));
+}
+
+export function input(node: HTMLInputElement, state: Signal<unknown>): void {
+  effect(() => { const value = String(state.get() ?? ''); if (node.value !== value) node.value = value; });
+  listen(node, 'input', () => state.set(node.value));
+}
+
+export function component(parent: Node, view: Component): void {
+  scope(() => view(parent));
+}

package/src/heshjs/index.ts

@@ -0,0 +1,4 @@
+export { signal, effect, derived, batch, scope, onCleanup, untrack } from '../reactivity/index.js';
+export type { Signal, Disposer } from '../reactivity/index.js';
+export { mount, element, text, attribute, listen, input, component } from '../dom/index.js';
+export type { Component, MountOptions } from '../dom/index.js';

package/src/parser/index.ts

@@ -0,0 +1,149 @@
+import ts from 'typescript';
+export interface Location { start: number; end: number }
+export interface Expression extends Location { source: string }
+export interface State extends Location { kind: 'state' | 'const'; name: string; value: Expression }
+export interface Element extends Location { kind: 'element'; name: string; value?: Expression; handler?: Expression; async: boolean; children: Element[] }
+export interface View extends Location { name: string; exported: boolean; default: boolean; body: (State | Element)[] }
+export interface Module { source: string; filename: string; imports: Expression[]; views: View[] }
+export class HeshError extends Error {
+  readonly line: number;
+  readonly column: number;
+  constructor(message: string, readonly source: string, readonly offset: number, readonly filename = 'component.hesh') {
+    const lines = source.slice(0, offset).split('\n');
+    const line = lines.length, column = lines.at(-1)!.length + 1;
+    super(`${filename}:${line}:${column}: ${message}`);
+    this.name = 'HeshError'; this.line = line; this.column = column;
+  }
+}
+export interface Token extends Location { text: string; kind: ts.SyntaxKind }
+export function tokenize(source: string, filename = 'component.hesh'): Token[] {
+  const tokens: Token[] = [];
+  const keywords = new Set('break case catch class const continue debugger default delete do else enum export extends false finally for function if import in instanceof new null return super switch this throw true try typeof var void while with yield let static await async'.split(' '));
+  let at = 0;
+  const fail = (message: string, offset: number): never => { throw new HeshError(message, source, offset, filename); };
+  while (at < source.length) {
+    const start = at;
+    const ch = source[at]!;
+    if (/\s/.test(ch)) { at++; continue; }
+    if (source.startsWith('//', at)) { while (at < source.length && source[at] !== '\n') at++; continue; }
+    if (source.startsWith('/*', at)) {
+      const end = source.indexOf('*/', at + 2);
+      if (end < 0) fail('Unterminated comment', at);
+      at = end + 2; continue;
+    }
+    let kind = ts.SyntaxKind.Unknown;
+    if (ch === '"' || ch === "'" || ch === '`') {
+      const quote = ch;
+      at++; let closed = false;
+      while (at < source.length) {
+        const current = source[at++]!;
+        if (current === '\\') { at++; continue; }
+        if (quote === '`' && current === '$' && source[at] === '{') fail('Template substitutions belong in imported JS/TS helpers in Milestone 1', at - 1);
+        if (current === quote) { closed = true; break; }
+        if (quote !== '`' && (current === '\n' || current === '\r')) fail('Unterminated string', start);
+      }
+      if (!closed) fail('Unterminated string', start);
+      kind = quote === '`' ? ts.SyntaxKind.NoSubstitutionTemplateLiteral : ts.SyntaxKind.StringLiteral;
+    } else if (/[$_\p{ID_Start}]/u.test(ch)) {
+      at++;
+      while (at < source.length && /[$\u200c\u200d\p{ID_Continue}]/u.test(source[at]!)) at++;
+      kind = keywords.has(source.slice(start, at)) ? ts.SyntaxKind.Unknown : ts.SyntaxKind.Identifier;
+    } else if (/\d/.test(ch)) {
+      at++;
+      while (at < source.length && /[\w.]/.test(source[at]!)) at++;
+      kind = ts.SyntaxKind.NumericLiteral;
+    } else {
+      const operator = ['>>>=', '===', '!==', '**=', '&&=', '||=', '??=', '>>>', '<<=', '>>=', '=>', '==', '!=', '<=', '>=', '++', '--', '+=', '-=', '*=', '/=', '%=', '**', '&&', '||', '??', '?.', '<<', '>>', '&=', '|=', '^=', '...'].find(op => source.startsWith(op, at));
+      at += operator?.length ?? 1;
+    }
+    tokens.push({ kind, text: source.slice(start, at), start, end: at });
+  }
+  return tokens;
+}
+
+export function parse(source: string, filename = 'component.hesh'): Module {
+  const tokens = tokenize(source, filename);
+  let at = 0;
+  const peek = () => tokens[at]?.text;
+  const fail = (message: string, offset = tokens[at]?.start ?? source.length): never => { throw new HeshError(message, source, offset, filename); };
+  const take = (text?: string): Token => {
+    const token = tokens[at];
+    if (!token || (text !== undefined && token.text !== text)) fail(`Expected ${text ?? 'token'}, received ${peek() ?? 'end of file'}`);
+    at++; return token!;
+  };
+  const identifier = () => {
+    const token = take();
+    if (token.kind !== ts.SyntaxKind.Identifier) fail('Expected identifier', token.start);
+    if (token.text.startsWith('__h')) fail('Identifiers beginning __h are reserved', token.start);
+    return token;
+  };
+  const expression = (ends: string[]): Expression => {
+    const start = tokens[at]?.start ?? source.length;
+    const stack: string[] = [];
+    const pairs: Record<string, string> = { '(': ')', '[': ']', '{': '}' };
+    while (tokens[at]) {
+      const token = tokens[at]!;
+      if (!stack.length && ends.includes(token.text)) break;
+      if (pairs[token.text]) stack.push(pairs[token.text]!);
+      else if ([')', ']', '}'].includes(token.text)) {
+        if (stack.pop() !== token.text) fail('Unbalanced expression', token.start);
+      }
+      at++;
+    }
+    if (stack.length) fail('Unterminated expression', start);
+    const end = tokens[at]?.start ?? source.length;
+    if (!source.slice(start, end).trim()) fail('Expected expression', start);
+    return { source: source.slice(start, end).trimEnd(), start, end };
+  };
+  const element = (): Element => {
+    const name = identifier(); take('(');
+    let value: Expression | undefined, handler: Expression | undefined, async = false;
+    if (peek() !== ')') value = expression([',', ')']);
+    if (peek() === ',') {
+      take(',');
+      if (peek() === 'async') { take(); async = true; }
+      const start = take('{').end;
+      let depth = 1;
+      while (tokens[at] && depth) {
+        if (peek() === '{') depth++;
+        if (peek() === '}') depth--;
+        if (depth) at++;
+      }
+      if (!tokens[at]) fail('Unterminated event block', start);
+      const end = take('}').start;
+      handler = { source: source.slice(start, end), start, end };
+    }
+    take(')');
+    const children: Element[] = [];
+    if (peek() === '{') { take(); while (peek() && peek() !== '}') children.push(element()); take('}'); if (peek() === ';') take(); }
+    else take(';');
+    return { kind: 'element', name: name.text, start: name.start, end: tokens[at - 1]!.end, value, handler, async, children };
+  };
+  const module: Module = { source, filename, imports: [], views: [] };
+  while (tokens[at]) {
+    if (peek() === 'import') {
+      if (module.views.length) fail('Imports must precede views');
+      const start = take().start;
+      while (peek() && peek() !== ';') take();
+      const end = take(';').end;
+      module.imports.push({ source: source.slice(start, end), start, end }); continue;
+    }
+    let exported = false, isDefault = false;
+    if (peek() === 'export') { take(); exported = true; }
+    if (peek() === 'default') { take(); isDefault = true; if (!exported) fail('default requires export'); }
+    const start = take('view').start;
+    const name = identifier().text; take('{');
+    const body: (State | Element)[] = [];
+    while (peek() && peek() !== '}') {
+      if (peek() === 'const' || tokens[at + 1]?.text === '=') {
+        const kind = peek() === 'const' ? (take(), 'const' as const) : 'state' as const;
+        const name = identifier(); take('='); const value = expression([';']); const end = take(';').end;
+        body.push({ kind, name: name.text, value, start: name.start, end });
+      } else body.push(element());
+    }
+    const end = take('}').end;
+    module.views.push({ name, body, start, end, exported, default: isDefault });
+  }
+  if (!module.views.length) fail('Expected at least one view');
+  return module;
+}

package/src/reactivity/index.ts

@@ -0,0 +1,115 @@
+export type Disposer = () => void;
+export interface Signal<T> { get(): T; set(value: T): T }
+interface Observer { run(): void; deps: Set<Set<Observer>>; disposed: boolean; computed: boolean }
+interface Owner { cleanups: Set<Disposer>; disposed: boolean }
+let active: Observer | undefined;
+let owner: Owner | undefined;
+let depth = 0;
+let flushing = false;
+const queue = new Set<Observer>();
+
+function flush(): void {
+  if (depth || flushing) return;
+  flushing = true;
+  let steps = 0;
+  try {
+    while (queue.size) {
+      if (++steps > 1000) throw new Error('HeshJS reactive update limit exceeded');
+      const next = [...queue].find(o => o.computed) ?? queue.values().next().value!;
+      queue.delete(next);
+      if (!next.disposed) next.run();
+    }
+  } catch (error) { queue.clear(); throw error; }
+  finally { flushing = false; }
+}
+
+export function signal<T>(initial: T): Signal<T> {
+  let value = initial;
+  const subscribers = new Set<Observer>();
+  return {
+    get() { if (active) { subscribers.add(active); active.deps.add(subscribers); } return value; },
+    set(next) {
+      if (!Object.is(value, next)) {
+        value = next;
+        for (const observer of subscribers) queue.add(observer);
+        flush();
+      }
+      return value;
+    }
+  };
+}
+
+export function onCleanup(fn: Disposer): void {
+  if (!owner) throw new Error('onCleanup requires a reactive scope');
+  if (owner.disposed) fn(); else owner.cleanups.add(fn);
+}
+
+export function scope<T>(fn: () => T): { value: T; dispose: Disposer } {
+  const parent = owner;
+  const current: Owner = { cleanups: new Set(), disposed: false };
+  const dispose = () => {
+    if (current.disposed) return;
+    current.disposed = true;
+    parent?.cleanups.delete(dispose);
+    const errors: unknown[] = [];
+    for (const cleanup of [...current.cleanups].reverse()) {
+      try { cleanup(); } catch (error) { errors.push(error); }
+    }
+    current.cleanups.clear();
+    if (errors.length) throw new AggregateError(errors, 'HeshJS cleanup failed');
+  };
+  parent?.cleanups.add(dispose);
+  owner = current;
+  try { return { value: fn(), dispose }; }
+  catch (error) { dispose(); throw error; }
+  finally { owner = parent; }
+}
+
+export function effect(fn: () => void, computed = false): Disposer {
+  const owningScope = owner;
+  let runScope: { dispose: Disposer } | undefined;
+  const observer: Observer = {
+    deps: new Set(), disposed: false, computed,
+    run() {
+      for (const dep of observer.deps) dep.delete(observer);
+      observer.deps.clear();
+      runScope?.dispose();
+      const previous = active;
+      const previousOwner = owner;
+      active = observer;
+      owner = owningScope;
+      depth++;
+      try { runScope = scope(fn); }
+      finally { active = previous; owner = previousOwner; depth--; }
+    }
+  };
+  const dispose = () => {
+    if (observer.disposed) return;
+    observer.disposed = true;
+    owningScope?.cleanups.delete(dispose);
+    queue.delete(observer);
+    for (const dep of observer.deps) dep.delete(observer);
+    observer.deps.clear();
+    runScope?.dispose();
+  };
+  owningScope?.cleanups.add(dispose);
+  try { observer.run(); flush(); } catch (error) { dispose(); throw error; }
+  return dispose;
+}
+
+export function derived<T>(fn: () => T): Pick<Signal<T>, 'get'> {
+  const value = signal<T>(undefined as T);
+  effect(() => value.set(fn()), true);
+  return { get: value.get };
+}
+
+export function batch<T>(fn: () => T): T {
+  depth++;
+  try { return fn(); } finally { depth--; flush(); }
+}
+
+export function untrack<T>(fn: () => T): T {
+  const previous = active;
+  active = undefined;
+  try { return fn(); } finally { active = previous; }
+}

package/src/vite/index.ts

@@ -0,0 +1,17 @@
+import type { Plugin } from 'vite';
+import { compile } from '../compiler/index.js';
+export function hesh(): Plugin {
+  let production = false;
+  return {
+    name: 'heshjs', enforce: 'pre',
+    configResolved(config) { production = config.command === 'build'; },
+    transform(source, id) {
+      if (!id.endsWith('.hesh')) return;
+      const result = compile(source, { filename: id, development: !production });
+      return { code: result.code, map: null };
+    },
+    handleHotUpdate(context) {
+      if (context.file.endsWith('.hesh')) { context.server.ws.send({ type: 'full-reload' }); return []; }
+    }
+  };
+}