@hyperfixi/types-browser 3.3.0 → 4.0.0

package/src/index.ts

@@ -31,26 +31,26 @@
  *
  * ### Using window.hyperfixi
  * ```typescript
- * // window.hyperfixi is now fully typed
- * const result = await window.hyperfixi.execute('toggle .active')
- * window.evalHyperScript('toggle .active')
+ * // window.hyperfixi (and window._hyperscript, the same object) is fully typed
+ * window.hyperfixi.evaluate('toggle .active on me', { me: button })
+ * window.hyperfixi.parse('on click toggle .active').errors // []
  * ```
  *
- * ### Using window.HyperFixiSemantic
+ * ### Using window.LokaScriptSemantic
  * ```typescript
- * if (window.HyperFixiSemantic) {
- *   const node = window.HyperFixiSemantic.parse('toggle .active', 'en')
- *   const japanese = window.HyperFixiSemantic.translate('toggle .active', 'en', 'ja')
+ * if (window.LokaScriptSemantic) {
+ *   const node = window.LokaScriptSemantic.parse('toggle .active', 'en')
+ *   const japanese = window.LokaScriptSemantic.translate('toggle .active', 'en', 'ja')
  * }
  * ```
  *
  * ### Using Type Guards
  * ```typescript
- * import { isHyperFixiCoreAvailable, getHyperFixiCore } from '@hyperfixi/types-browser'
+ * import { getHyperFixiCore } from '@hyperfixi/types-browser'
  *
  * const hyperfixi = getHyperFixiCore()
  * if (hyperfixi) {
- *   hyperfixi.execute('toggle .active')
+ *   hyperfixi.evaluate('toggle .active on me', { me: button })
  * }
  * ```
  */

package/src/type-guards.ts

@@ -2,19 +2,19 @@
  * Type guards for browser globals
  */
 
-import type { LokaScriptCoreAPI } from './core-api';
+import type { HyperfixiAPI } from './core-api';
 import type { LokaScriptSemanticAPI } from './semantic-api';
 import type { LokaScriptI18nAPI } from './i18n-api';
 
 /**
- * Check if window.hyperfixi is available and properly typed
+ * Check that a value is the hyperscript host (`window.hyperfixi` / `window._hyperscript`):
+ * callable, with `evaluate` and `processNode`.
  */
-export function isHyperFixiCoreAvailable(obj?: any): obj is LokaScriptCoreAPI {
+export function isHyperFixiCoreAvailable(obj?: any): obj is HyperfixiAPI {
   return (
-    typeof obj === 'object' &&
-    obj !== null &&
-    typeof obj.execute === 'function' &&
-    typeof obj.compile === 'function'
+    typeof obj === 'function' &&
+    typeof obj.evaluate === 'function' &&
+    typeof obj.processNode === 'function'
   );
 }
 
@@ -48,7 +48,7 @@ export function isHyperFixiI18nAvailable(obj?: any): obj is LokaScriptI18nAPI {
 /**
  * Safe access to window.hyperfixi with type checking
  */
-export function getHyperFixiCore(): LokaScriptCoreAPI | null {
+export function getHyperFixiCore(): HyperfixiAPI | null {
   if (typeof window !== 'undefined' && isHyperFixiCoreAvailable(window.hyperfixi)) {
     return window.hyperfixi;
   }

package/src/core-api.d.ts

@@ -1,280 +0,0 @@
-/**
- * Type definitions for @hyperfixi/core browser global (window.hyperfixi)
- */
-
-export interface LokaScriptCoreAPI {
-  // ==================== API v2 (Recommended) ====================
-
-  /**
-   * Synchronously compile hyperscript code to AST.
-   * Use this for English-only code that needs synchronous compilation.
-   *
-   * @example
-   * ```typescript
-   * const result = hyperfixi.compileSync('toggle .active');
-   * if (result.ok) {
-   *   console.log('Parser used:', result.meta.parser);
-   *   await hyperfixi.execute(result.ast, element);
-   * }
-   * ```
-   *
-   * @since API v2
-   */
-  compileSync(source: string, options?: NewCompileOptions): CompileResult;
-
-  /**
-   * Asynchronously compile hyperscript code (handles all 13 languages).
-   * Use this for multilingual support or when async compilation is acceptable.
-   *
-   * @example
-   * ```typescript
-   * // English
-   * const result = await hyperfixi.compile('toggle .active');
-   *
-   * // Japanese
-   * const result = await hyperfixi.compile('トグル .active', { language: 'ja' });
-   * ```
-   *
-   * @since API v2
-   */
-  compile(source: string, options?: NewCompileOptions): Promise<CompileResult>;
-
-  /**
-   * Compile and execute hyperscript in one step.
-   *
-   * @example
-   * ```typescript
-   * // With context
-   * const ctx = hyperfixi.createContext(element);
-   * await hyperfixi.eval('toggle .active', ctx);
-   *
-   * // With element directly
-   * await hyperfixi.eval('toggle .active', element);
-   * ```
-   *
-   * @since API v2
-   */
-  eval(source: string, contextOrElement?: ExecutionContext | Element): Promise<any>;
-
-  /**
-   * Validate hyperscript syntax and return detailed errors.
-   *
-   * @example
-   * ```typescript
-   * const result = await hyperfixi.validate('toggle .active');
-   * if (result.valid) {
-   *   console.log('Valid syntax');
-   * } else {
-   *   result.errors?.forEach(err => {
-   *     console.error(`Line ${err.line}: ${err.message}`);
-   *   });
-   * }
-   * ```
-   *
-   * @since API v2
-   */
-  validate(source: string, options?: NewCompileOptions): Promise<ValidateResult>;
-
-  /**
-   * Create execution context (unified signature with optional parent).
-   *
-   * @example
-   * ```typescript
-   * // Basic context
-   * const ctx = hyperfixi.createContext(element);
-   *
-   * // Child context
-   * const child = hyperfixi.createContext(element, parentContext);
-   * ```
-   *
-   * @since API v2
-   */
-  createContext(element?: Element | null, parent?: ExecutionContext): ExecutionContext;
-
-  // ==================== API v1 (Deprecated) ====================
-
-  /**
-   * Execute hyperscript on an element
-   */
-  execute(source: string, element?: Element, context?: ExecutionOptions): Promise<void>;
-
-  /**
-   * @deprecated Use `eval()` instead
-   * Run (compile and execute) hyperscript
-   */
-  run(source: string, element?: Element): Promise<void>;
-
-  /**
-   * @deprecated Use `eval()` instead
-   * Alias for run()
-   */
-  evaluate(source: string, element?: Element): Promise<void>;
-
-  /**
-   * Parse hyperscript to AST
-   */
-  parse(source: string): ParseResult;
-
-  /**
-   * Process a DOM node for hyperscript attributes
-   */
-  processNode(node: Node): void;
-
-  /**
-   * Process entire document for hyperscript
-   */
-  process(root?: Document | Element): void;
-
-  /**
-   * @deprecated Use `createContext(element, parent)` instead
-   * Create child execution context
-   */
-  createChildContext(parent: ExecutionContext, element?: Element): ExecutionContext;
-
-  /**
-   * @deprecated Use `validate()` instead
-   * Validate hyperscript syntax
-   */
-  isValidHyperscript(source: string): boolean;
-
-  /**
-   * Get HyperFixi version
-   */
-  version: string;
-
-  /**
-   * Create runtime instance
-   */
-  createRuntime(options?: RuntimeOptions): Runtime;
-}
-
-export interface CompileOptions {
-  strict?: boolean;
-  includeSource?: boolean;
-}
-
-export interface CompilationResult {
-  ast: ASTNode;
-  errors: ParseError[];
-  success: boolean;
-}
-
-export interface ParseResult {
-  ast: ASTNode;
-  tokens: Token[];
-  errors: ParseError[];
-}
-
-export interface ParseError {
-  message: string;
-  position: number;
-  line: number;
-  column: number;
-}
-
-export interface Token {
-  type: string;
-  value: string;
-  position: number;
-  line: number;
-  column: number;
-}
-
-export interface ASTNode {
-  type: string;
-  [key: string]: unknown;
-}
-
-export interface ExecutionOptions {
-  globals?: Record<string, unknown>;
-  locals?: Record<string, unknown>;
-}
-
-export interface ExecutionContext {
-  me: Element | null;
-  you?: Element | null;
-  it?: unknown;
-  result?: unknown;
-  locals: Map<string, unknown>;
-  globals: Map<string, unknown>;
-  target?: Element | EventTarget | null;
-  detail?: unknown;
-}
-
-export interface ContextOptions {
-  element?: Element;
-  globals?: Record<string, unknown>;
-}
-
-export interface RuntimeOptions {
-  strict?: boolean;
-  timeout?: number;
-}
-
-export interface Runtime {
-  execute(ast: ASTNode, context: ExecutionContext): Promise<void>;
-  processCommand(command: ASTNode, context: ExecutionContext): Promise<void>;
-}
-
-// ==================== API v2 Types ====================
-
-/**
- * Result of compilation (API v2)
- */
-export interface CompileResult {
-  /** Whether compilation succeeded */
-  ok: boolean;
-  /** Compiled AST (only present if ok=true) */
-  ast?: ASTNode;
-  /** Compilation errors (only present if ok=false) */
-  errors?: CompileError[];
-  /** Compilation metadata */
-  meta: {
-    /** Parser used: semantic or traditional */
-    parser: 'semantic' | 'traditional';
-    /** Confidence score (0-1) if semantic parser was used */
-    confidence?: number;
-    /** Language code */
-    language: string;
-    /** Compilation time in milliseconds */
-    timeMs: number;
-    /** Whether direct path was taken (no fallback) */
-    directPath?: boolean;
-  };
-}
-
-/**
- * Compilation error (API v2)
- */
-export interface CompileError {
-  /** Error message */
-  message: string;
-  /** Line number where error occurred */
-  line: number;
-  /** Column number where error occurred */
-  column: number;
-  /** Optional suggestion for fixing the error */
-  suggestion?: string;
-}
-
-/**
- * Compilation options (API v2)
- */
-export interface NewCompileOptions {
-  /** Language code (default: 'en') */
-  language?: string;
-  /** Minimum confidence for semantic parsing (0-1, default: 0.5) */
-  confidenceThreshold?: number;
-  /** Force traditional parser, skip semantic analysis */
-  traditional?: boolean;
-}
-
-/**
- * Validation result (API v2)
- */
-export interface ValidateResult {
-  /** Whether code is valid */
-  valid: boolean;
-  /** Validation errors (only present if valid=false) */
-  errors?: CompileError[];
-}

package/src/i18n-api.d.ts

@@ -1,47 +0,0 @@
-/**
- * Type definitions for @lokascript/i18n browser global (window.HyperFixiI18n)
- */
-
-/**
- * NOTE: this file and `i18n-api.ts` both declare `LokaScriptI18nAPI`, with
- * different shapes — `index.d.ts` references this one, `index.ts` exports the
- * other. That divergence predates this change and is untouched here; only the
- * retired transformer surface is removed from both.
- */
-export interface LokaScriptI18nAPI {
-  // RETIRED 2026-08-28 with `@lokascript/i18n`'s grammar transformer:
-  // `translate` and `createTransformer` (plus the `GrammarTransformer` and
-  // `TransformerOptions` interfaces they referenced). Translation is
-  // `@lokascript/semantic`'s job; in the browser that is `hyperfixi.translate`
-  // from the multilingual bundle.
-
-  /**
-   * Get supported locales
-   */
-  supportedLocales: readonly string[];
-
-  /**
-   * Get language profile for a locale
-   */
-  getProfile(locale: string): LanguageProfile | undefined;
-}
-
-export interface LanguageProfile {
-  locale: string;
-  wordOrder: 'SVO' | 'SOV' | 'VSO';
-  adpositions: 'prepositions' | 'postpositions' | 'both';
-  morphology: 'isolating' | 'agglutinative' | 'fusional';
-  markers?: Record<string, string>;
-}
-
-export interface ParsedStatement {
-  action: string;
-  roles: Map<string, ParsedElement>;
-  raw: string;
-}
-
-export interface ParsedElement {
-  role: string;
-  value: string;
-  type: 'literal' | 'selector' | 'reference';
-}

package/src/index.d.ts

@@ -1,28 +0,0 @@
-/**
- * @hyperfixi/types-browser
- * TypeScript type definitions for HyperFixi browser globals
- *
- * This package provides complete type definitions for using HyperFixi
- * packages in the browser via global variables.
- *
- * Install with: npm install --save-dev @hyperfixi/types-browser
- *
- * Then add to your tsconfig.json:
- * ```json
- * {
- *   "compilerOptions": {
- *     "types": ["@hyperfixi/types-browser"]
- *   }
- * }
- * ```
- */
-
-/// <reference path="./core-api.d.ts" />
-/// <reference path="./semantic-api.d.ts" />
-/// <reference path="./i18n-api.d.ts" />
-/// <reference path="./globals.d.ts" />
-
-// Re-export all types for convenience
-export * from './core-api';
-export * from './semantic-api';
-export * from './i18n-api';

package/src/semantic-api.d.ts

@@ -1,74 +0,0 @@
-/**
- * Type definitions for @lokascript/semantic browser global (window.HyperFixiSemantic)
- */
-
-export interface LokaScriptSemanticAPI {
-  /**
-   * Parse hyperscript in any supported language
-   */
-  parse(source: string, language: string): SemanticNode;
-
-  /**
-   * Translate hyperscript between languages
-   */
-  translate(source: string, fromLang: string, toLang: string): string;
-
-  /**
-   * Get all translations for a source in all supported languages
-   */
-  getAllTranslations(source: string, sourceLang: string): Record<string, string>;
-
-  /**
-   * Create a semantic analyzer instance
-   */
-  createSemanticAnalyzer(options?: SemanticAnalyzerOptions): SemanticAnalyzer;
-
-  /**
-   * Get list of supported languages
-   */
-  supportedLanguages: readonly string[];
-}
-
-export interface SemanticNode {
-  kind: string;
-  action: string;
-  roles: ReadonlyMap<string, SemanticValue>;
-  confidence: number;
-  metadata?: {
-    sourcePosition?: {
-      start: number;
-      end: number;
-    };
-  };
-}
-
-export interface SemanticValue {
-  type: 'literal' | 'selector' | 'reference' | 'property-path' | 'expression';
-  value: string | number | boolean;
-  dataType?: string;
-  selectorKind?: string;
-  object?: SemanticValue;
-  property?: string;
-  raw?: string;
-}
-
-export interface SemanticAnalyzer {
-  analyze(input: string, language: string): AnalysisResult;
-  supportsLanguage(language: string): boolean;
-  supportedLanguages(): string[];
-}
-
-export interface SemanticAnalyzerOptions {
-  confidenceThreshold?: number;
-  languages?: string[];
-}
-
-export interface AnalysisResult {
-  confidence: number;
-  command?: {
-    name: string;
-    roles: ReadonlyMap<string, SemanticValue>;
-  };
-  errors?: string[];
-  tokensConsumed?: number;
-}