@hyperfixi/core 3.1.1 → 3.3.0

package/README.md

@@ -1,4 +1,4 @@
-# @lokascript/core
+# @hyperfixi/core
 
 An experimental hyperscript engine that provides fast parsing, command execution, and comprehensive error handling for web applications. Built with TypeScript-first design.
 
@@ -7,7 +7,7 @@ An experimental hyperscript engine that provides fast parsing, command execution
 - 🎯 **\_hyperscript Compatible** - Tested via gallery examples, bundle compatibility matrix, and command/expression browser tests
 - 🚀 **High Performance** - Optimized tokenizer and parser for large expressions
 - 🔧 **TypeScript First** - Complete type safety with comprehensive type definitions
-- 🧪 **Thoroughly Tested** - 2800+ tests with 98.5%+ reliability
+- 🧪 **Thoroughly Tested** - Vitest unit suites plus Playwright browser tests
 - 🌊 **Complete Command System** - All major commands implemented (PUT, SET, ADD, SHOW/HIDE, etc.)
 - ⚡ **HTML Integration** - Automatic `_=""` attribute processing and event binding
 - 🛡️ **Error Recovery** - Graceful handling of syntax errors with helpful guidance
@@ -15,26 +15,26 @@ An experimental hyperscript engine that provides fast parsing, command execution
 ## Installation
 
 ```bash
-npm install @lokascript/core
+npm install @hyperfixi/core
 # or
-yarn add @lokascript/core
+yarn add @hyperfixi/core
 ```
 
 ## Quick Start
 
 ```typescript
-import { hyperscript } from '@lokascript/core';
+import { hyperscript } from '@hyperfixi/core';
 
 // Simple expression evaluation
-const result = await hyperscript.run('5 + 3 * 2'); // Returns 11
+const result = await hyperscript.eval('5 + 3 * 2'); // Returns 11
 
 // DOM manipulation with commands
 const button = document.getElementById('myButton');
 const context = hyperscript.createContext(button);
 
-await hyperscript.run('hide me', context); // Hides the button
-await hyperscript.run('put "Hello World" into my innerHTML', context);
-await hyperscript.run('set my className to "active"', context);
+await hyperscript.eval('hide me', context); // Hides the button
+await hyperscript.eval('put "Hello World" into my innerHTML', context);
+await hyperscript.eval('set my className to "active"', context);
 ```
 
 ### HTML Integration (Automatic)
@@ -52,18 +52,18 @@ await hyperscript.run('set my className to "active"', context);
 
 ## Debugging
 
-LokaScript includes a built-in debug control API for troubleshooting compilation and execution issues.
+HyperFixi includes a built-in debug control API for troubleshooting compilation and execution issues.
 
 ### Enable Debug Logging
 
 ```javascript
 // In browser console
-lokascript.debugControl.enable(); // Enable detailed logging
+hyperfixi.debugControl.enable(); // Enable detailed logging
 // Reload page to see logs
 
-lokascript.debugControl.disable(); // Disable logging
-lokascript.debugControl.isEnabled(); // Check if enabled
-lokascript.debugControl.status(); // Get detailed status
+hyperfixi.debugControl.disable(); // Disable logging
+hyperfixi.debugControl.isEnabled(); // Check if enabled
+hyperfixi.debugControl.status(); // Get detailed status
 ```
 
 Debug settings persist across page reloads via localStorage. Logs include:
@@ -94,13 +94,13 @@ that fell back to its English rendering — reports.
 
 ## Runtime Hooks
 
-LokaScript provides a hooks system for observing and intercepting command execution:
+HyperFixi provides a hooks system for observing and intercepting command execution:
 
 ```javascript
-import { HookRegistry, createHooks } from '@lokascript/core';
+import { hyperscript } from '@hyperfixi/core';
 
 // Create hooks for logging, analytics, or debugging
-const hooks = createHooks({
+const hooks = {
   beforeExecute: ctx => {
     console.log(`Executing: ${ctx.commandName}`);
   },
@@ -115,34 +115,26 @@ const hooks = createHooks({
     // Return true to skip command execution
     return name === 'disabled-command';
   },
-});
+};
 
 // Register hooks with the runtime
-lokascript.registerHooks('my-hooks', hooks);
+hyperscript.registerHooks('my-hooks', hooks);
 ```
 
-Built-in hook utilities:
-
-- `loggingHooks()` - Pre-configured debug logging hooks
-- `createTimingHooks()` - Performance timing hooks
-
 ## Cleanup & Memory Management
 
 The runtime automatically tracks event listeners and observers for cleanup when elements are removed from the DOM. You can also manually trigger cleanup:
 
 ```javascript
-// Clean up a specific element
-lokascript.cleanup(element);
-
-// Clean up element and all descendants
-lokascript.cleanupTree(containerElement);
+// Clean up an element and all its descendants
+hyperscript.cleanup(containerElement);
 
 // Get cleanup statistics
-const stats = lokascript.getCleanupStats();
+const stats = hyperscript.getDefaultRuntime().getCleanupStats();
 // { elementsTracked: 5, listeners: 12, observers: 2, ... }
 
 // Full runtime shutdown
-lokascript.destroy();
+hyperscript.getDefaultRuntime().destroy();
 ```
 
 ## API Reference
@@ -153,12 +145,12 @@ For complete API documentation, see [API.md](./docs/API.md).
 
 - `hyperscript.compile(code)` - Compile hyperscript to AST
 - `hyperscript.execute(ast, context)` - Execute compiled AST
-- `hyperscript.run(code, context)` - Compile and execute in one step
+- `hyperscript.eval(code, context)` - Compile and execute in one step
 - `hyperscript.createContext(element)` - Create execution context
-- `evalHyperScript(code, context)` - \_hyperscript compatibility API
+- `evalHyperScript(code, context)` - \_hyperscript compatibility API (a global in the `hyperfixi.js` browser bundle)
 - `hyperscript.registerHooks(name, hooks)` - Register runtime hooks
-- `hyperscript.cleanup(element)` - Clean up element resources
-- `hyperscript.destroy()` - Full runtime shutdown
+- `hyperscript.cleanup(element)` - Clean up an element and its descendants
+- `hyperscript.getDefaultRuntime().destroy()` - Full runtime shutdown
 
 ## Supported Features
 
@@ -193,7 +185,7 @@ See [EXAMPLES.md](./docs/EXAMPLES.md) for comprehensive usage examples.
 
 ## Compatibility Testing
 
-This package includes compatibility tests that validate LokaScript against the official \_hyperscript library:
+This package includes compatibility tests that validate HyperFixi against the official \_hyperscript library:
 
 ```bash
 # Run compatibility tests with official hyperscript test suite

package/dist/ast/command-slots.d.ts

@@ -58,7 +58,7 @@ export declare const COMMAND_SLOTS: {
     readonly throw: readonly [];
     readonly toggle: readonly ["as", "between", "for", "from", "on", "until"];
     readonly unless: readonly [];
-    readonly transition: readonly ["on", "over", "to", "with"];
+    readonly transition: readonly ["from", "on", "over", "pairs", "to", "using", "with"];
     readonly trigger: readonly ["on", "to", "with"];
     readonly wait: readonly [];
 };

package/dist/ast/nodes.d.ts

@@ -60,6 +60,7 @@ export interface CallExpressionNode extends BaseNode {
     readonly callee: Expr;
     readonly arguments: Expr[];
     readonly isConstructor?: boolean;
+    readonly closestTo?: Expr;
 }
 export interface MemberExpressionNode extends BaseNode {
     readonly type: 'memberExpression';
@@ -182,6 +183,7 @@ export interface EventHandlerNode extends BaseNode {
     readonly events?: string[];
     readonly condition?: Expr;
     readonly target?: string;
+    readonly targetExpression?: Expr;
     readonly selector?: string;
     readonly args?: string[];
     readonly attributeName?: string;

package/dist/ast-utils/index.cjs

@@ -2254,6 +2254,14 @@ function convertNode(node, infer) {
                 ...pos(node),
             };
         case 'identifier':
+            if (node.scope === 'element' || node.scope === 'local' || node.scope === 'global') {
+                return {
+                    type: 'variable',
+                    name: (node.name ?? ''),
+                    scope: node.scope,
+                    ...pos(node),
+                };
+            }
             return {
                 type: 'identifier',
                 value: (node.name ?? node.value ?? ''),
@@ -2276,6 +2284,15 @@ function convertNode(node, infer) {
                 operand: convertNode(node.argument ?? node.operand, infer),
                 ...pos(node),
             };
+        case 'typeCheckExpression':
+            return {
+                type: 'typeCheck',
+                value: convertNode(node.value, infer),
+                typeName: String(node.typeName),
+                nullOk: node.nullOk !== false,
+                negated: node.negated === true,
+                ...pos(node),
+            };
         case 'timeExpression':
             return { type: 'literal', value: node.value, ...pos(node) };
         case 'templateLiteral':
@@ -2287,6 +2304,28 @@ function convertNode(node, infer) {
                 scope: (node.scope ?? 'local'),
                 ...pos(node),
             };
+        case 'arrayLiteral':
+            return {
+                type: 'array',
+                elements: (node.elements ?? []).map(element => convertNode(element, infer)),
+                ...pos(node),
+            };
+        case 'attributeAccess':
+            return {
+                type: 'possessive',
+                object: { type: 'identifier', value: 'me' },
+                property: `@${node.attributeName}`,
+                ...pos(node),
+            };
+        case 'propertyOfExpression': {
+            const property = node.property;
+            return {
+                type: 'possessive',
+                object: convertNode(node.target, infer),
+                property: (property?.name ?? property?.value ?? ''),
+                ...pos(node),
+            };
+        }
         case 'htmlSelector':
             return {
                 type: 'selector',
@@ -2338,6 +2377,21 @@ function convertCommand$1(node, infer) {
     if (name === 'repeat') {
         return convertRepeatCommand(node, infer);
     }
+    const original = node.originalCommand;
+    const sum = node.modifiers?.to;
+    const counted = node.args?.[0];
+    if (name === 'set' &&
+        (original === 'increment' || original === 'decrement') &&
+        sum?.type === 'binaryExpression' &&
+        counted) {
+        return convertCommand$1({
+            ...node,
+            name: original,
+            args: [counted],
+            modifiers: { by: sum.right },
+            originalCommand: undefined,
+        }, infer);
+    }
     const args = (node.args ?? []).map(arg => convertNode(arg, infer));
     const target = node.target ? convertNode(node.target, infer) : undefined;
     const modifiers = node.modifiers
@@ -2386,6 +2440,64 @@ function convertIfCommand(node, infer) {
     };
 }
 function convertRepeatCommand(node, infer) {
+    const slots = (node.modifiers ?? {});
+    const form = slotText(slots.loopType);
+    if (form === undefined)
+        return convertPositionalRepeat(node, infer);
+    const [bodyBlock, elseBlock] = (node.args ?? []);
+    const body = extractBlockCommands(bodyBlock, infer);
+    const indexName = slotText(slots.index);
+    const shared = {
+        ...(indexName ? { indexName } : {}),
+        ...(elseBlock ? { elseBody: extractBlockCommands(elseBlock, infer) } : {}),
+        ...pos(node),
+    };
+    const operand = (slot) => (slot ? convertNode(slot, infer) : undefined);
+    switch (form) {
+        case 'for':
+            return {
+                type: 'foreach',
+                itemName: slotText(slots.for) ?? 'it',
+                collection: operand(slots.in) ?? { type: 'literal', value: null },
+                body,
+                ...shared,
+            };
+        case 'times':
+            return { type: 'repeat', count: operand(slots.times), body, ...shared };
+        case 'while':
+        case 'until': {
+            const test = operand(slots[form]) ?? { type: 'literal', value: form === 'until' };
+            return {
+                type: 'while',
+                condition: form === 'until' ? { type: 'unary', operator: 'not', operand: test } : test,
+                ...(slots.bottomTested?.value === true ? { bottomTested: true } : {}),
+                body,
+                ...shared,
+            };
+        }
+        case 'until-event': {
+            const event = slotText(slots.event);
+            if (!event) {
+                return { type: 'error', message: "'repeat until event' has no event name", ...pos(node) };
+            }
+            const target = operand(slots.from);
+            return {
+                type: 'repeat',
+                untilEvent: event,
+                ...(target ? { untilEventTarget: target } : {}),
+                body,
+                ...shared,
+            };
+        }
+        default:
+            return { type: 'repeat', body, ...shared };
+    }
+}
+function slotText(slot) {
+    const text = slot?.value ?? slot?.name;
+    return typeof text === 'string' ? text : undefined;
+}
+function convertPositionalRepeat(node, infer) {
     const args = (node.args ?? []);
     if (args.length === 0) {
         return { type: 'repeat', body: [], ...pos(node) };
@@ -2702,6 +2814,15 @@ function toCoreAST(node) {
                 prefix: true,
                 ...nodePos(node),
             };
+        case 'typeCheck':
+            return {
+                type: 'typeCheckExpression',
+                value: toCoreAST(node.value),
+                typeName: node.typeName,
+                nullOk: node.nullOk,
+                negated: node.negated,
+                ...nodePos(node),
+            };
         case 'member':
             return {
                 type: 'memberExpression',
@@ -2712,6 +2833,12 @@ function toCoreAST(node) {
                 computed: node.computed ?? false,
                 ...nodePos(node),
             };
+        case 'array':
+            return {
+                type: 'arrayLiteral',
+                elements: node.elements.map(element => toCoreAST(element)),
+                ...nodePos(node),
+            };
         case 'possessive':
             return {
                 type: 'possessiveExpression',
@@ -2774,72 +2901,85 @@ function convertCommand(node) {
     }
     return result;
 }
+function block(nodes) {
+    return { type: 'block', commands: nodes.map(n => toCoreAST(n)), ...POS };
+}
 function convertIf(node) {
-    const result = {
+    const [elseIf, ...laterElseIfs] = node.elseIfBranches ?? [];
+    const elseBranch = elseIf
+        ? [
+            {
+                type: 'if',
+                condition: elseIf.condition,
+                thenBranch: elseIf.body,
+                elseIfBranches: laterElseIfs,
+                ...(node.elseBranch ? { elseBranch: node.elseBranch } : {}),
+            },
+        ]
+        : node.elseBranch;
+    return {
         type: 'command',
         name: 'if',
         isBlocking: true,
-        condition: toCoreAST(node.condition),
-        thenBranch: node.thenBranch.map(n => toCoreAST(n)),
-        args: [],
+        args: [
+            toCoreAST(node.condition),
+            block(node.thenBranch),
+            ...(elseBranch ? [block(elseBranch)] : []),
+        ],
         ...nodePos(node),
     };
-    if (node.elseBranch) {
-        result.elseBranch = node.elseBranch.map(n => toCoreAST(n));
-    }
-    return result;
 }
-function convertRepeat(node) {
-    const result = {
+function loopCommand(node, form, operands) {
+    const modifiers = { loopType: slotString(form) };
+    for (const [slot, value] of Object.entries(operands)) {
+        if (value)
+            modifiers[slot] = value;
+    }
+    if (node.indexName)
+        modifiers.index = slotString(node.indexName);
+    return {
         type: 'command',
         name: 'repeat',
         isBlocking: true,
-        body: node.body.map(n => toCoreAST(n)),
-        args: [],
+        args: [block(node.body), ...(node.elseBody ? [block(node.elseBody)] : [])],
+        modifiers,
         ...nodePos(node),
     };
+}
+function slotString(value) {
+    return { type: 'string', value, ...POS };
+}
+function convertRepeat(node) {
     if (node.count !== undefined) {
-        result.count =
-            typeof node.count === 'number'
-                ? { type: 'literal', value: node.count, raw: String(node.count), ...POS }
-                : toCoreAST(node.count);
-        result.loopVariant = 'times';
-    }
-    else if (node.whileCondition !== undefined) {
-        result.condition = toCoreAST(node.whileCondition);
-        result.loopVariant = 'while';
-    }
-    else if (node.untilEvent !== undefined) {
-        result.untilEvent = node.untilEvent;
-        result.loopVariant = 'until';
+        const times = typeof node.count === 'number'
+            ? { type: 'literal', value: node.count, raw: String(node.count), ...POS }
+            : toCoreAST(node.count);
+        return loopCommand(node, 'times', { times });
+    }
+    if (node.whileCondition !== undefined) {
+        return loopCommand(node, 'while', { while: toCoreAST(node.whileCondition) });
+    }
+    if (node.untilEvent !== undefined) {
+        return loopCommand(node, 'until-event', {
+            event: slotString(node.untilEvent),
+            from: node.untilEventTarget ? toCoreAST(node.untilEventTarget) : undefined,
+        });
     }
-    return result;
+    return loopCommand(node, 'forever', {});
 }
 function convertForEach(node) {
-    return {
-        type: 'command',
-        name: 'repeat',
-        isBlocking: true,
-        loopVariant: 'for',
-        itemName: node.itemName,
-        ...(node.indexName ? { indexName: node.indexName } : {}),
-        collection: toCoreAST(node.collection),
-        body: node.body.map(n => toCoreAST(n)),
-        args: [],
-        ...nodePos(node),
-    };
+    return loopCommand(node, 'for', {
+        for: slotString(node.itemName),
+        in: toCoreAST(node.collection),
+    });
 }
 function convertWhile(node) {
-    return {
-        type: 'command',
-        name: 'repeat',
-        isBlocking: true,
-        loopVariant: 'while',
-        condition: toCoreAST(node.condition),
-        body: node.body.map(n => toCoreAST(n)),
-        args: [],
-        ...nodePos(node),
-    };
+    return loopCommand(node, 'while', {
+        while: toCoreAST(node.condition),
+        bottomTested: node.bottomTested
+            ? { type: 'literal', value: true, raw: 'true', ...POS }
+            : undefined,
+    });
 }
 function flattenEventModifiers(modifiers) {
     if (!modifiers)
@@ -3243,6 +3383,9 @@ function getChildren(node) {
         case 'unary':
             children.push(node.operand);
             break;
+        case 'typeCheck':
+            children.push(node.value);
+            break;
         case 'member': {
             const m = node;
             children.push(m.object);
@@ -3380,6 +3523,8 @@ function friendlyTypeName(node) {
             return `Binary Expression (${node.operator})`;
         case 'unary':
             return `Unary Expression (${node.operator})`;
+        case 'typeCheck':
+            return `Type Check (${node.typeName})`;
         case 'literal':
             return 'Literal';
         case 'identifier':