@hyperfixi/types-browser 2.0.0

package/src/semantic-api.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 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;
+}

package/src/semantic-api.ts

@@ -0,0 +1,242 @@
+/**
+ * Type definitions for HyperFixi Semantic browser API
+ */
+
+export type SupportedLanguage =
+  | 'en'
+  | 'ja'
+  | 'ar'
+  | 'es'
+  | 'ko'
+  | 'tr'
+  | 'zh'
+  | 'pt'
+  | 'fr'
+  | 'de'
+  | 'id'
+  | 'qu'
+  | 'sw';
+
+/**
+ * HyperFixi semantic parser API exposed on window.HyperFixiSemantic
+ */
+export interface LokaScriptSemanticAPI {
+  /**
+   * Parse hyperscript in any supported language to semantic representation
+   *
+   * @param code Hyperscript code to parse
+   * @param language Two-letter language code (en, ja, ar, es, ko, tr, zh, pt, fr, de, id, qu, sw)
+   * @returns Parsed semantic node or null
+   */
+  parse(code: string, language: SupportedLanguage): SemanticNode | null;
+
+  /**
+   * Check if hyperscript can be parsed in a language
+   */
+  canParse(code: string, language: SupportedLanguage): boolean;
+
+  /**
+   * Parse in any supported language (auto-detect)
+   */
+  parseAny(code: string): SemanticNode | null;
+
+  /**
+   * Parse explicit syntax
+   */
+  parseExplicit(code: string): any | null;
+
+  /**
+   * Check if code uses explicit syntax
+   */
+  isExplicitSyntax(code: string): boolean;
+
+  /**
+   * Translate hyperscript between languages
+   */
+  translate(
+    code: string,
+    fromLanguage: SupportedLanguage,
+    toLanguage: SupportedLanguage
+  ): string | null;
+
+  /**
+   * Get all translations of hyperscript in supported languages
+   */
+  getAllTranslations(
+    code: string,
+    fromLanguage: SupportedLanguage
+  ): Record<SupportedLanguage, string>;
+
+  /**
+   * Round-trip translation validation
+   */
+  roundTrip(code: string, language: SupportedLanguage): boolean;
+
+  /**
+   * Validate translation accuracy
+   */
+  validateTranslation(
+    original: string,
+    translated: string,
+    fromLang: SupportedLanguage,
+    toLang: SupportedLanguage
+  ): boolean;
+
+  /**
+   * Render semantic node to hyperscript
+   */
+  render(node: SemanticNode, language: SupportedLanguage): string;
+
+  /**
+   * Render to explicit syntax
+   */
+  renderExplicit(node: SemanticNode): string;
+
+  /**
+   * Convert to explicit syntax
+   */
+  toExplicit(code: string, language: SupportedLanguage): string | null;
+
+  /**
+   * Convert from explicit syntax
+   */
+  fromExplicit(code: string, language: SupportedLanguage): string | null;
+
+  /**
+   * Create semantic analyzer
+   */
+  createSemanticAnalyzer(options?: any): any;
+
+  /**
+   * Check if semantic result should be used
+   */
+  shouldUseSemanticResult(semanticNode: SemanticNode | null, fallbackNode: any): boolean;
+
+  /**
+   * Build AST from semantic node
+   */
+  buildAST(node: SemanticNode): any;
+
+  /**
+   * Tokenize code in a specific language
+   */
+  tokenize(code: string, language: SupportedLanguage): any[];
+
+  /**
+   * Get tokenizer for a language
+   */
+  getTokenizer(language: SupportedLanguage): any;
+
+  /**
+   * Check if language is supported
+   */
+  isLanguageSupported(language: string): boolean;
+
+  /**
+   * Get list of supported language codes
+   */
+  getSupportedLanguages(): SupportedLanguage[];
+
+  /**
+   * Create CSS selector helper
+   */
+  createSelector(value: string): any;
+
+  /**
+   * Create literal value helper
+   */
+  createLiteral(value: any): any;
+
+  /**
+   * Create reference helper
+   */
+  createReference(name: string): any;
+
+  /**
+   * Create property path helper
+   */
+  createPropertyPath(path: string[]): any;
+
+  /**
+   * Create command node helper
+   */
+  createCommandNode(command: string, options?: any): any;
+
+  /**
+   * Create event handler helper
+   */
+  createEventHandler(event: string, options?: any): any;
+
+  /**
+   * Get command mapper
+   */
+  getCommandMapper(command: string): any;
+
+  /**
+   * Register command mapper
+   */
+  registerCommandMapper(command: string, mapper: any): void;
+
+  /**
+   * Package version
+   */
+  VERSION: string;
+
+  /**
+   * Default confidence threshold
+   */
+  DEFAULT_CONFIDENCE_THRESHOLD: number;
+
+  /**
+   * High confidence threshold
+   */
+  HIGH_CONFIDENCE_THRESHOLD: number;
+
+  /**
+   * Language-specific tokenizers
+   */
+  englishTokenizer: any;
+  japaneseTokenizer: any;
+  koreanTokenizer: any;
+  arabicTokenizer: any;
+  spanishTokenizer: any;
+  turkishTokenizer: any;
+  chineseTokenizer: any;
+  portugueseTokenizer: any;
+  frenchTokenizer: any;
+  germanTokenizer: any;
+  indonesianTokenizer: any;
+  quechuaTokenizer: any;
+  swahiliTokenizer: any;
+
+  /**
+   * Semantic analyzer implementation
+   */
+  SemanticAnalyzerImpl: any;
+
+  /**
+   * AST Builder class
+   */
+  ASTBuilder: any;
+}
+
+export interface SemanticNode {
+  action: string;
+  roles: Map<string, SemanticValue>;
+  confidence: number;
+  errors?: ValidationError[];
+  tokens?: any[];
+  [key: string]: any;
+}
+
+export interface SemanticValue {
+  value: any;
+  type?: string;
+  [key: string]: any;
+}
+
+export interface ValidationError {
+  message: string;
+  code?: string;
+  [key: string]: any;
+}

package/src/type-guards.ts

@@ -0,0 +1,73 @@
+/**
+ * Type guards for browser globals
+ */
+
+import type { LokaScriptCoreAPI } from './core-api';
+import type { LokaScriptSemanticAPI } from './semantic-api';
+import type { LokaScriptI18nAPI } from './i18n-api';
+
+/**
+ * Check if window.hyperfixi is available and properly typed
+ */
+export function isHyperFixiCoreAvailable(obj?: any): obj is LokaScriptCoreAPI {
+  return (
+    typeof obj === 'object' &&
+    obj !== null &&
+    typeof obj.execute === 'function' &&
+    typeof obj.compile === 'function'
+  );
+}
+
+/**
+ * Check if window.HyperFixiSemantic is available
+ */
+export function isHyperFixiSemanticAvailable(obj?: any): obj is LokaScriptSemanticAPI {
+  return (
+    typeof obj === 'object' &&
+    obj !== null &&
+    typeof obj.parse === 'function' &&
+    typeof obj.canParse === 'function'
+  );
+}
+
+/**
+ * Check if window.HyperFixiI18n is available
+ */
+export function isHyperFixiI18nAvailable(obj?: any): obj is LokaScriptI18nAPI {
+  return (
+    typeof obj === 'object' &&
+    obj !== null &&
+    typeof obj.translate === 'function' &&
+    typeof obj.getSupportedLocales === 'function'
+  );
+}
+
+/**
+ * Safe access to window.hyperfixi with type checking
+ */
+export function getHyperFixiCore(): LokaScriptCoreAPI | null {
+  if (typeof window !== 'undefined' && isHyperFixiCoreAvailable(window.hyperfixi)) {
+    return window.hyperfixi;
+  }
+  return null;
+}
+
+/**
+ * Safe access to window.LokaScriptSemantic with type checking
+ */
+export function getHyperFixiSemantic(): LokaScriptSemanticAPI | null {
+  if (typeof window !== 'undefined' && isHyperFixiSemanticAvailable(window.LokaScriptSemantic)) {
+    return window.LokaScriptSemantic;
+  }
+  return null;
+}
+
+/**
+ * Safe access to window.LokaScriptI18n with type checking
+ */
+export function getHyperFixiI18n(): LokaScriptI18nAPI | null {
+  if (typeof window !== 'undefined' && isHyperFixiI18nAvailable(window.LokaScriptI18n)) {
+    return window.LokaScriptI18n;
+  }
+  return null;
+}