@hyperfixi/types-browser 2.0.0

package/src/core-api.ts

@@ -0,0 +1,261 @@
+/**
+ * Type definitions for HyperFixi Core browser API
+ */
+
+/**
+ * HyperFixi core API exposed on window.hyperfixi
+ */
+export interface LokaScriptCoreAPI {
+  // ==================== API v2 (Recommended) ====================
+
+  /**
+   * Synchronously compile hyperscript code to AST (API v2).
+   * @since API v2
+   */
+  compileSync(code: string, options?: NewCompileOptions): CompileResult;
+
+  /**
+   * Asynchronously compile hyperscript code (handles all 13 languages) (API v2).
+   * @since API v2
+   */
+  compile(code: string, options?: NewCompileOptions): Promise<CompileResult>;
+
+  /**
+   * Compile and execute hyperscript in one step (API v2).
+   * @since API v2
+   */
+  eval(code: string, contextOrElement?: any): Promise<any>;
+
+  /**
+   * Validate hyperscript syntax and return detailed errors (API v2).
+   * @since API v2
+   */
+  validate(code: string, options?: NewCompileOptions): Promise<ValidateResult>;
+
+  /**
+   * Create execution context with optional parent (unified signature, API v2).
+   * @since API v2
+   */
+  createContext(element?: Element | null, parent?: any): any;
+
+  // ==================== API v1 (Deprecated) ====================
+
+  /**
+   * Evaluate hyperscript string directly
+   */
+  evalHyperScript(code: string, element?: Element): any;
+
+  /**
+   * Async evaluation of hyperscript
+   */
+  evalHyperScriptAsync(code: string, element?: Element): Promise<any>;
+
+  /**
+   * Smart evaluation with automatic context detection
+   */
+  evalHyperScriptSmart(code: string): Promise<any>;
+
+  /**
+   * Compile multilingual hyperscript code
+   * @deprecated Use compile() with options.language instead
+   */
+  compileMultilingual(code: string, language: string, options?: CompileOptions): CompilationResult;
+
+  /**
+   * Execute hyperscript code
+   */
+  execute(code: string, element?: Element, options?: ExecuteOptions): Promise<any>;
+
+  /**
+   * Run hyperscript code (alias for execute)
+   * @deprecated Use eval() instead
+   */
+  run(code: string, element?: Element, options?: ExecuteOptions): Promise<any>;
+
+  /**
+   * Create child execution context
+   * @deprecated Use createContext(element, parent) instead
+   */
+  createChildContext(parent: any, element?: Element): any;
+
+  /**
+   * Validate hyperscript syntax (returns boolean)
+   * @deprecated Use validate() instead (returns detailed result)
+   */
+  isValidHyperscript(code: string): boolean;
+
+  /**
+   * Create runtime instance
+   */
+  createRuntime(options?: RuntimeOptions): any;
+
+  /**
+   * Process DOM node
+   */
+  processNode(node: Node): void;
+
+  /**
+   * Process DOM node (alias)
+   */
+  process(node: Node): void;
+
+  /**
+   * Tokenize hyperscript code
+   */
+  tokenize(code: string): any[];
+
+  /**
+   * Low-level parser access
+   */
+  Parser: any;
+
+  /**
+   * Low-level runtime access
+   */
+  Runtime: any;
+
+  /**
+   * Attribute processor
+   */
+  attributeProcessor: any;
+
+  /**
+   * Tailwind extension
+   */
+  tailwindExtension: any;
+
+  /**
+   * Debug utilities
+   */
+  debug: {
+    enableDebugLogging(): void;
+    disableDebugLogging(): void;
+  };
+
+  /**
+   * Style batcher utility
+   */
+  styleBatcher: any;
+
+  /**
+   * Object pool utility
+   */
+  ObjectPool: any;
+
+  /**
+   * Semantic parsing utilities
+   */
+  semantic?: {
+    parse(code: string, language: string): any;
+    translate(code: string, fromLang: string, toLang: string): string | null;
+    buildAST(node: any): any;
+  };
+
+  /**
+   * Semantic debug utilities
+   */
+  semanticDebug?: any;
+
+  /**
+   * Version string
+   */
+  version: string;
+}
+
+export interface CompileOptions {
+  language?: string;
+  strict?: boolean;
+  [key: string]: any;
+}
+
+export interface CompilationResult {
+  success: boolean;
+  code?: any;
+  error?: Error;
+  [key: string]: any;
+}
+
+export interface ExecuteOptions {
+  context?: any;
+  element?: Element;
+  [key: string]: any;
+}
+
+export interface ContextOptions {
+  element?: Element;
+  globals?: Record<string, any>;
+  [key: string]: any;
+}
+
+export interface RuntimeOptions {
+  [key: string]: any;
+}
+
+export type EvalHyperScriptFunction = (code: string, element?: Element) => any;
+
+export type EvalHyperScriptAsyncFunction = (code: string, element?: Element) => Promise<any>;
+
+export type EvalHyperScriptSmartFunction = (code: string) => Promise<any>;
+
+// ==================== API v2 Types ====================
+
+/**
+ * Compilation result (API v2)
+ */
+export interface CompileResult {
+  /** Whether compilation succeeded */
+  ok: boolean;
+  /** Compiled AST (only present if ok=true) */
+  ast?: any;
+  /** 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/globals.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Global type augmentation for HyperFixi and LokaScript browser APIs
+ *
+ * This file augments the Window and globalThis interfaces to include
+ * HyperFixi and LokaScript global variables, providing IDE autocomplete and type safety.
+ */
+
+import type { LokaScriptCoreAPI } from './core-api';
+import type { LokaScriptSemanticAPI } from './semantic-api';
+import type { LokaScriptI18nAPI } from './i18n-api';
+
+declare global {
+  /**
+   * Window interface augmentation
+   */
+  interface Window {
+    /**
+     * HyperFixi - Modern hyperscript engine with fixi/htmx integration
+     *
+     * Loaded from: hyperfixi.js or hyperfixi-hx.js
+     *
+     * @example
+     * ```typescript
+     * window.hyperfixi.execute('toggle .active', document.body)
+     * window.hyperfixi.compile('on click add .highlight')
+     * ```
+     */
+    hyperfixi: LokaScriptCoreAPI;
+
+    /**
+     * @deprecated Use `hyperfixi` instead. Will be removed in v3.0.0.
+     *
+     * Loaded from: hyperfixi.js (backward-compat alias)
+     */
+    lokascript: LokaScriptCoreAPI;
+
+    /**
+     * Compatibility alias for official _hyperscript API compatibility
+     *
+     * @example
+     * ```typescript
+     * window._hyperscript.compile('on click toggle .active')
+     * ```
+     */
+    _hyperscript: LokaScriptCoreAPI;
+
+    /**
+     * LokaScript Semantic - Multilingual semantic parsing (24 languages)
+     *
+     * Loaded from: lokascript-semantic.browser.global.js
+     *
+     * @example
+     * ```typescript
+     * const result = window.LokaScriptSemantic.parse('トグル .active', 'ja')
+     * const korean = window.LokaScriptSemantic.translate('toggle .active', 'en', 'ko')
+     * ```
+     */
+    LokaScriptSemantic: LokaScriptSemanticAPI;
+
+    /**
+     * LokaScript I18n - Grammar transformation for natural language word order
+     *
+     * Loaded from: lokascript-i18n.min.js
+     *
+     * @example
+     * ```typescript
+     * const japanese = window.LokaScriptI18n.translate('on click toggle .active', 'en', 'ja')
+     * // Result: 'クリック で .active を 切り替え' (SOV word order)
+     * ```
+     */
+    LokaScriptI18n: LokaScriptI18nAPI;
+  }
+
+  /**
+   * globalThis interface augmentation (same as Window for browser contexts)
+   */
+  var hyperfixi: LokaScriptCoreAPI;
+  var lokascript: LokaScriptCoreAPI;
+  var _hyperscript: LokaScriptCoreAPI;
+  var LokaScriptSemantic: LokaScriptSemanticAPI;
+  var LokaScriptI18n: LokaScriptI18nAPI;
+}
+
+// This export ensures the file is treated as a module
+export {};

package/src/i18n-api.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Type definitions for @lokascript/i18n browser global (window.HyperFixiI18n)
+ */
+
+export interface LokaScriptI18nAPI {
+  /**
+   * Translate hyperscript with grammar transformation
+   */
+  translate(source: string, fromLang: string, toLang: string): string;
+
+  /**
+   * Create a grammar transformer instance
+   */
+  createTransformer(options?: TransformerOptions): GrammarTransformer;
+
+  /**
+   * Get supported locales
+   */
+  supportedLocales: readonly string[];
+
+  /**
+   * Get language profile for a locale
+   */
+  getProfile(locale: string): LanguageProfile | undefined;
+}
+
+export interface GrammarTransformer {
+  transform(source: string, fromLang: string, toLang: string): string;
+  parseStatement(source: string, language: string): ParsedStatement;
+  toLocale(statement: ParsedStatement, locale: string): string;
+  toEnglish(source: string, locale: string): string;
+}
+
+export interface TransformerOptions {
+  strict?: boolean;
+  preserveWhitespace?: boolean;
+}
+
+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/i18n-api.ts

@@ -0,0 +1,209 @@
+/**
+ * Type definitions for HyperFixi i18n/Grammar transformation browser API
+ */
+
+/**
+ * HyperFixi i18n/Grammar transformation API on window.HyperFixiI18n
+ */
+export interface LokaScriptI18nAPI {
+  /**
+   * Transform hyperscript statement from one language word order to another
+   *
+   * @param statement Parsed hyperscript statement
+   * @param fromLocale Source language locale (e.g., 'en')
+   * @param toLocale Target language locale (e.g., 'ja')
+   * @returns Transformed statement or null
+   */
+  translate(
+    statement: HyperscriptStatement,
+    fromLocale: string,
+    toLocale: string
+  ): HyperscriptStatement | null;
+
+  /**
+   * Transform code from English to target locale
+   */
+  toLocale(code: string, toLocale: string): string | null;
+
+  /**
+   * Transform code from any locale to English
+   */
+  toEnglish(code: string, fromLocale: string): string | null;
+
+  /**
+   * Parse hyperscript statement
+   */
+  parseStatement(code: string): HyperscriptStatement | null;
+
+  /**
+   * Get supported locales for grammar transformation
+   */
+  getSupportedLocales(): string[];
+
+  /**
+   * Check if transformation is supported between two locales
+   */
+  supportsTransform(fromLocale: string, toLocale: string): boolean;
+
+  /**
+   * Get language profile information
+   */
+  getProfile(locale: string): LanguageProfile | null;
+
+  /**
+   * Reorder semantic roles based on language word order
+   */
+  reorderRoles(
+    roles: Record<string, any>,
+    fromProfile: LanguageProfile,
+    toProfile: LanguageProfile
+  ): Record<string, any>;
+
+  /**
+   * Insert grammatical markers
+   */
+  insertMarkers(tokens: string[], role: string, profile: LanguageProfile): string[];
+
+  /**
+   * Join tokens with language-specific rules
+   */
+  joinTokens(tokens: string[], profile: LanguageProfile): string;
+
+  /**
+   * Transform statement between locales
+   */
+  transformStatement(
+    statement: HyperscriptStatement,
+    fromProfile: LanguageProfile,
+    toProfile: LanguageProfile
+  ): HyperscriptStatement;
+
+  /**
+   * Check if direct word mapping exists
+   */
+  hasDirectMapping(word: string, fromLocale: string, toLocale: string): boolean;
+
+  /**
+   * Get direct word mapping
+   */
+  getDirectMapping(word: string, fromLocale: string, toLocale: string): string | null;
+
+  /**
+   * Translate word directly using mapping
+   */
+  translateWordDirect(word: string, fromLocale: string, toLocale: string): string | null;
+
+  /**
+   * Get supported language pairs for direct translation
+   */
+  getSupportedDirectPairs(): Array<[string, string]>;
+
+  /**
+   * Detect browser locale
+   */
+  detectBrowserLocale(): string;
+
+  /**
+   * Grammar transformer class
+   */
+  GrammarTransformer: any;
+
+  /**
+   * Locale manager class
+   */
+  LocaleManager: any;
+
+  /**
+   * Universal patterns for all languages
+   */
+  UNIVERSAL_PATTERNS: any;
+
+  /**
+   * Language family defaults
+   */
+  LANGUAGE_FAMILY_DEFAULTS: any;
+
+  /**
+   * All language profiles
+   */
+  profiles: Record<string, LanguageProfile>;
+
+  /**
+   * Language-specific profiles
+   */
+  englishProfile: LanguageProfile;
+  japaneseProfile: LanguageProfile;
+  koreanProfile: LanguageProfile;
+  arabicProfile: LanguageProfile;
+  spanishProfile: LanguageProfile;
+  turkishProfile: LanguageProfile;
+  chineseProfile: LanguageProfile;
+  portugueseProfile: LanguageProfile;
+  frenchProfile: LanguageProfile;
+  germanProfile: LanguageProfile;
+  indonesianProfile: LanguageProfile;
+  quechuaProfile: LanguageProfile;
+  swahiliProfile: LanguageProfile;
+
+  /**
+   * Language-specific keyword dictionaries
+   */
+  esDictionary: any;
+  jaDictionary: any;
+  frDictionary: any;
+  deDictionary: any;
+  arDictionary: any;
+  koDictionary: any;
+  zhDictionary: any;
+  trDictionary: any;
+  idDictionary: any;
+  quDictionary: any;
+  swDictionary: any;
+  ptDictionary: any;
+
+  /**
+   * Language-specific keywords
+   */
+  esKeywords: any;
+  jaKeywords: any;
+  frKeywords: any;
+  deKeywords: any;
+  arKeywords: any;
+  koKeywords: any;
+  zhKeywords: any;
+  trKeywords: any;
+  idKeywords: any;
+  quKeywords: any;
+  swKeywords: any;
+  ptKeywords: any;
+
+  /**
+   * Direct mapping configuration
+   */
+  directMappings: any;
+
+  /**
+   * Grammar transformation examples
+   */
+  grammarExamples: Array<{
+    english: string;
+    [locale: string]: string;
+  }>;
+}
+
+export interface HyperscriptStatement {
+  command: string;
+  roles: Record<string, any>;
+  modifiers?: string[];
+  [key: string]: any;
+}
+
+export interface LanguageProfile {
+  locale: string;
+  name: string;
+  wordOrder: 'SVO' | 'SOV' | 'VSO' | 'VOS';
+  isRTL: boolean;
+  family?: string;
+  joinTokens?: Record<string, string>;
+  [key: string]: any;
+}

package/src/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @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/index.ts

@@ -0,0 +1,62 @@
+/**
+ * @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.
+ *
+ * ## Installation
+ *
+ * ```bash
+ * npm install --save-dev @hyperfixi/types-browser
+ * ```
+ *
+ * ## Usage
+ *
+ * Add to your tsconfig.json:
+ * ```json
+ * {
+ *   "compilerOptions": {
+ *     "types": ["@hyperfixi/types-browser"]
+ *   }
+ * }
+ * ```
+ *
+ * Or use triple-slash directive in your TypeScript files:
+ * ```typescript
+ * /// <reference types="@hyperfixi/types-browser" />
+ * ```
+ *
+ * ## Examples
+ *
+ * ### Using window.hyperfixi
+ * ```typescript
+ * // window.hyperfixi is now fully typed
+ * const result = await window.hyperfixi.execute('toggle .active')
+ * window.evalHyperScript('toggle .active')
+ * ```
+ *
+ * ### Using window.HyperFixiSemantic
+ * ```typescript
+ * if (window.HyperFixiSemantic) {
+ *   const node = window.HyperFixiSemantic.parse('toggle .active', 'en')
+ *   const japanese = window.HyperFixiSemantic.translate('toggle .active', 'en', 'ja')
+ * }
+ * ```
+ *
+ * ### Using Type Guards
+ * ```typescript
+ * import { isHyperFixiCoreAvailable, getHyperFixiCore } from '@hyperfixi/types-browser'
+ *
+ * const hyperfixi = getHyperFixiCore()
+ * if (hyperfixi) {
+ *   hyperfixi.execute('toggle .active')
+ * }
+ * ```
+ */
+
+export * from './core-api';
+export * from './semantic-api';
+export * from './i18n-api';
+export * from './type-guards';
+export * from './globals';