@lokascript/semantic 1.0.0

package/src/bridge.ts

@@ -0,0 +1,275 @@
+/**
+ * Runtime Bridge
+ *
+ * Connects the semantic parser to the LokaScript core runtime.
+ * Converts SemanticNodes to the CommandNode format expected by the runtime.
+ */
+
+import type { SemanticNode, EventHandlerSemanticNode, SemanticValue } from './types';
+
+// =============================================================================
+// CommandNode Interface (from @lokascript/core)
+// =============================================================================
+
+/**
+ * Simplified CommandNode interface matching core runtime expectations.
+ * In production, this would import from @lokascript/core.
+ */
+interface CommandNode {
+  type: 'command';
+  name: string;
+  args: ExpressionNode[];
+  modifiers?: Record<string, ExpressionNode>;
+  body?: StatementNode[];
+  implicitTarget?: ExpressionNode;
+  isBlocking: boolean;
+  start?: number;
+  end?: number;
+  line?: number;
+  column?: number;
+}
+
+interface EventHandlerNode {
+  type: 'eventHandler';
+  eventName: string;
+  body: StatementNode[];
+  filter?: ExpressionNode;
+  modifiers?: {
+    once?: boolean;
+    debounce?: number;
+    throttle?: number;
+  };
+}
+
+type ExpressionNode = {
+  type: string;
+  [key: string]: unknown;
+};
+
+type StatementNode = CommandNode | EventHandlerNode | ExpressionNode;
+
+// =============================================================================
+// Semantic to Runtime Bridge
+// =============================================================================
+
+/**
+ * Convert a SemanticNode to a CommandNode for runtime execution.
+ */
+export function toCommandNode(semantic: SemanticNode): CommandNode {
+  const args: ExpressionNode[] = [];
+  const modifiers: Record<string, ExpressionNode> = {};
+
+  // Map semantic roles to CommandNode structure
+  for (const [role, value] of semantic.roles) {
+    const expr = valueToExpression(value);
+
+    switch (role) {
+      // Primary arguments (go into args array)
+      case 'patient':
+        args.push(expr);
+        break;
+
+      // Modifiers (go into modifiers object with preposition keys)
+      case 'destination':
+        // Determine appropriate preposition based on command
+        if (semantic.action === 'put') {
+          modifiers['into'] = expr;
+        } else {
+          modifiers['on'] = expr;
+        }
+        break;
+
+      case 'source':
+        modifiers['from'] = expr;
+        break;
+
+      case 'style':
+      case 'quantity':
+        modifiers['by'] = expr;
+        break;
+
+      case 'method':
+        modifiers['as'] = expr;
+        break;
+
+      case 'condition':
+        modifiers['if'] = expr;
+        break;
+
+      case 'event':
+        // For event handlers, this becomes the event name
+        args.push(expr);
+        break;
+
+      default:
+        // Unknown role - add as modifier
+        modifiers[role] = expr;
+    }
+  }
+
+  const result: CommandNode = {
+    type: 'command',
+    name: semantic.action,
+    args,
+    isBlocking: false,
+    start: semantic.metadata?.sourcePosition?.start ?? 0,
+    end: semantic.metadata?.sourcePosition?.end ?? 0,
+  };
+
+  if (Object.keys(modifiers).length > 0) {
+    result.modifiers = modifiers;
+  }
+
+  return result;
+}
+
+/**
+ * Convert a SemanticNode to an EventHandlerNode for runtime execution.
+ */
+export function toEventHandlerNode(semantic: EventHandlerSemanticNode): EventHandlerNode {
+  const eventValue = semantic.roles.get('event');
+  const eventName = eventValue ? valueToString(eventValue) : 'click';
+
+  const body: StatementNode[] = semantic.body.map(node => {
+    if (node.kind === 'event-handler') {
+      return toEventHandlerNode(node as EventHandlerSemanticNode);
+    }
+    return toCommandNode(node);
+  });
+
+  const result: EventHandlerNode = {
+    type: 'eventHandler',
+    eventName,
+    body,
+  };
+
+  if (semantic.eventModifiers) {
+    const mods: { once?: boolean; debounce?: number; throttle?: number } = {};
+    if (semantic.eventModifiers.once !== undefined) mods.once = semantic.eventModifiers.once;
+    if (semantic.eventModifiers.debounce !== undefined)
+      mods.debounce = semantic.eventModifiers.debounce;
+    if (semantic.eventModifiers.throttle !== undefined)
+      mods.throttle = semantic.eventModifiers.throttle;
+    if (Object.keys(mods).length > 0) {
+      result.modifiers = mods;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Convert a SemanticNode to the appropriate runtime node type.
+ */
+export function toRuntimeNode(semantic: SemanticNode): StatementNode {
+  if (semantic.kind === 'event-handler') {
+    return toEventHandlerNode(semantic as EventHandlerSemanticNode);
+  }
+  return toCommandNode(semantic);
+}
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Convert a SemanticValue to an ExpressionNode.
+ */
+function valueToExpression(value: SemanticValue): ExpressionNode {
+  switch (value.type) {
+    case 'literal':
+      return {
+        type: 'literal',
+        value: value.value,
+        dataType: value.dataType,
+      };
+
+    case 'selector':
+      return {
+        type: 'selector',
+        value: value.value,
+        selectorType: value.selectorKind,
+      };
+
+    case 'reference':
+      return {
+        type: 'identifier',
+        name: value.value,
+      };
+
+    case 'property-path':
+      return {
+        type: 'memberExpression',
+        object: valueToExpression(value.object),
+        property: {
+          type: 'identifier',
+          name: value.property,
+        },
+      };
+
+    case 'expression':
+      return {
+        type: 'raw',
+        value: value.raw,
+      };
+  }
+}
+
+/**
+ * Convert a SemanticValue to a string.
+ */
+function valueToString(value: SemanticValue): string {
+  switch (value.type) {
+    case 'literal':
+      return String(value.value);
+    case 'selector':
+      return value.value;
+    case 'reference':
+      return value.value;
+    case 'property-path':
+      return `${valueToString(value.object)}'s ${value.property}`;
+    case 'expression':
+      return value.raw;
+  }
+}
+
+// =============================================================================
+// Integration API
+// =============================================================================
+
+/**
+ * Parse multilingual hyperscript and return a runtime-compatible node.
+ *
+ * @param input Hyperscript input (any supported language)
+ * @param language Source language code
+ * @returns Runtime-compatible node
+ */
+export function parseToRuntime(input: string, language: string): StatementNode {
+  // Import here to avoid circular dependency
+  const { parse } = require('./parser');
+  const semantic = parse(input, language);
+  return toRuntimeNode(semantic);
+}
+
+/**
+ * Parse multilingual hyperscript and execute it.
+ * This is a placeholder - actual execution requires the core runtime.
+ *
+ * @param input Hyperscript input
+ * @param language Source language code
+ * @param context Execution context (from core runtime)
+ */
+export async function parseAndExecute(
+  input: string,
+  language: string,
+  _context: unknown
+): Promise<void> {
+  const node = parseToRuntime(input, language);
+
+  // In production, this would call the core runtime's execute function
+  console.log('Would execute:', JSON.stringify(node, null, 2));
+
+  // Placeholder for actual execution
+  // const runtime = context.runtime;
+  // await runtime.processCommand(node, context);
+}

package/src/browser-ar.ts

@@ -0,0 +1,162 @@
+/**
+ * Arabic Browser Bundle Entry Point
+ *
+ * Minimal single-language bundle.
+ * Estimated size: ~69 KB (~24 KB gzip)
+ *
+ * @example
+ * ```html
+ * <script src="hyperfixi-semantic.ar.global.js"></script>
+ * <script>
+ *   const ast = LokaScriptSemanticAr.parse('toggle .active', 'ar');
+ * </script>
+ * ```
+ */
+
+// =============================================================================
+// Register Languages: ar
+// =============================================================================
+
+import './languages/ar';
+
+// =============================================================================
+// Version
+// =============================================================================
+
+export const VERSION = '1.0.0-ar';
+
+// =============================================================================
+// Supported Languages
+// =============================================================================
+
+const SUPPORTED_LANGUAGES = ['ar'] as const;
+
+/**
+ * Get all supported languages in this bundle.
+ */
+export function getSupportedLanguages(): string[] {
+  return [...SUPPORTED_LANGUAGES];
+}
+
+/**
+ * Validate that a language is supported by this bundle.
+ */
+function validateLanguage(language: string): void {
+  if (language !== 'ar') {
+    throw new Error(`Language not supported in this bundle: ${language}. ` + `Supported: ar`);
+  }
+}
+
+// =============================================================================
+// Tokenizers (from registry)
+// =============================================================================
+
+export { getTokenizer, isLanguageSupported } from './registry';
+
+import type { LanguageToken } from './types';
+import { tokenize as tokenizeInternal } from './tokenizers';
+
+/**
+ * Tokenize input and return array of tokens (browser-friendly wrapper).
+ */
+export function tokenize(input: string, language: string): LanguageToken[] {
+  validateLanguage(language);
+  const stream = tokenizeInternal(input, language);
+  return [...stream.tokens];
+}
+
+// Re-export tokenizers
+export { arabicTokenizer } from './tokenizers/arabic';
+
+// =============================================================================
+// Patterns (from registry - lazy generation)
+// =============================================================================
+
+import { getPatternsForLanguage as getPatternsFromRegistry } from './registry';
+import type { LanguagePattern, ActionType } from './types';
+
+/**
+ * Get all patterns for a language.
+ */
+export function getPatternsForLanguage(language: string): LanguagePattern[] {
+  validateLanguage(language);
+  return getPatternsFromRegistry(language);
+}
+
+/**
+ * Get patterns for a language and specific command.
+ */
+export function getPatternsForLanguageAndCommand(
+  language: string,
+  command: ActionType
+): LanguagePattern[] {
+  return getPatternsForLanguage(language)
+    .filter(p => p.command === command)
+    .sort((a, b) => b.priority - a.priority);
+}
+
+// =============================================================================
+// Language Profiles (from registry)
+// =============================================================================
+
+export { getProfile, tryGetProfile } from './registry';
+export { arabicProfile } from './generators/language-profiles';
+
+// =============================================================================
+// Parsing
+// =============================================================================
+
+export { parse, canParse } from './parser';
+export { parseAny, parseExplicit, isExplicitSyntax } from './explicit';
+
+// =============================================================================
+// Rendering
+// =============================================================================
+
+export { render, renderExplicit, toExplicit, fromExplicit } from './explicit';
+
+// =============================================================================
+// AST Builder
+// =============================================================================
+
+export { buildAST, ASTBuilder, getCommandMapper, registerCommandMapper } from './ast-builder';
+
+// =============================================================================
+// Semantic Analyzer (for core parser integration)
+// =============================================================================
+
+export {
+  createSemanticAnalyzer,
+  SemanticAnalyzerImpl,
+  shouldUseSemanticResult,
+  DEFAULT_CONFIDENCE_THRESHOLD,
+  HIGH_CONFIDENCE_THRESHOLD,
+} from './core-bridge';
+
+export type { SemanticAnalyzer, SemanticAnalysisResult } from './core-bridge';
+
+// =============================================================================
+// Type Helpers
+// =============================================================================
+
+export {
+  createSelector,
+  createLiteral,
+  createReference,
+  createPropertyPath,
+  createCommandNode,
+  createEventHandler,
+} from './types';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type {
+  ActionType,
+  SemanticRole,
+  SemanticValue,
+  SemanticNode,
+  LanguageToken,
+  TokenStream,
+} from './types';

package/src/browser-core.ts

@@ -0,0 +1,231 @@
+/**
+ * Core Browser Bundle Entry Point (No Languages)
+ *
+ * A minimal browser bundle that includes only the parsing infrastructure.
+ * Languages must be loaded via URL or pre-loaded modules.
+ *
+ * This is ideal for:
+ * - CDN-based language loading
+ * - Applications that load languages dynamically from external sources
+ * - Minimizing initial bundle size
+ *
+ * @example
+ * ```html
+ * <script src="hyperfixi-semantic-core.global.js"></script>
+ * <script src="lang/en.global.js"></script> <!-- Self-registering -->
+ * <script>
+ *   const ast = LokaScriptSemanticCore.parse('toggle .active', 'en');
+ * </script>
+ * ```
+ *
+ * @example
+ * ```html
+ * <script src="hyperfixi-semantic-core.global.js"></script>
+ * <script>
+ *   // Load from URL
+ *   await LokaScriptSemanticCore.loadLanguageFromUrl('ja', '/lang/ja.global.js');
+ *   const ast = LokaScriptSemanticCore.parse('トグル .active', 'ja');
+ * </script>
+ * ```
+ */
+
+// =============================================================================
+// Version
+// =============================================================================
+
+export const VERSION = '1.0.0-core';
+
+// =============================================================================
+// Registry (Core)
+// =============================================================================
+
+export {
+  registerLanguage,
+  registerPatterns,
+  getTokenizer,
+  isLanguageSupported,
+  isLanguageRegistered,
+  getRegisteredLanguages,
+  getProfile,
+  tryGetProfile,
+  getPatternsForLanguage,
+  setPatternGenerator,
+} from './registry';
+
+// =============================================================================
+// Tokenizers
+// =============================================================================
+
+import type { LanguageToken } from './types';
+import { tokenize as tokenizeInternal } from './tokenizers';
+import { isLanguageRegistered } from './registry';
+
+/**
+ * Tokenize input and return array of tokens.
+ * @throws Error if language is not loaded
+ */
+export function tokenize(input: string, language: string): LanguageToken[] {
+  if (!isLanguageRegistered(language)) {
+    throw new Error(
+      `Language '${language}' is not loaded. ` + `Load it via script tag or loadLanguageFromUrl().`
+    );
+  }
+  const stream = tokenizeInternal(input, language);
+  return [...stream.tokens];
+}
+
+// =============================================================================
+// Parsing
+// =============================================================================
+
+export { parse, canParse } from './parser';
+export { parseAny, parseExplicit, isExplicitSyntax } from './explicit';
+
+// =============================================================================
+// Rendering
+// =============================================================================
+
+export { render, renderExplicit, toExplicit, fromExplicit } from './explicit';
+
+// =============================================================================
+// AST Builder
+// =============================================================================
+
+export { buildAST, ASTBuilder, getCommandMapper, registerCommandMapper } from './ast-builder';
+
+// =============================================================================
+// Semantic Analyzer (for core parser integration)
+// =============================================================================
+
+export {
+  createSemanticAnalyzer,
+  SemanticAnalyzerImpl,
+  shouldUseSemanticResult,
+  DEFAULT_CONFIDENCE_THRESHOLD,
+  HIGH_CONFIDENCE_THRESHOLD,
+} from './core-bridge';
+
+export type { SemanticAnalyzer, SemanticAnalysisResult } from './core-bridge';
+
+// =============================================================================
+// URL-Based Language Loading
+// =============================================================================
+
+import {
+  registerLanguage as regLang,
+  registerPatterns as regPatterns,
+  type LanguageProfile,
+} from './registry';
+import type { LanguageTokenizer, LanguagePattern } from './types';
+
+// Re-export for language module registration
+export type { LanguagePattern };
+
+/**
+ * A language module that can be registered.
+ */
+export interface LanguageModule {
+  tokenizer: LanguageTokenizer;
+  profile: LanguageProfile;
+  patterns?: LanguagePattern[];
+  buildPatterns?: () => LanguagePattern[];
+}
+
+/**
+ * Load a language from a URL.
+ *
+ * The URL should point to a JavaScript file that:
+ * - Either self-registers the language (recommended for IIFE bundles)
+ * - Or exports a LanguageModule object
+ *
+ * @example
+ * ```typescript
+ * // Load self-registering bundle
+ * await loadLanguageFromUrl('ja', '/lang/ja.global.js');
+ *
+ * // Load from CDN
+ * await loadLanguageFromUrl('ko', 'https://cdn.example.com/semantic/lang/ko.js');
+ * ```
+ */
+export async function loadLanguageFromUrl(
+  code: string,
+  url: string
+): Promise<{ loaded: boolean; error?: string }> {
+  try {
+    // Fetch the script
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    const text = await response.text();
+
+    // Execute the script (self-registering bundles will register themselves)
+    const script = document.createElement('script');
+    script.textContent = text;
+    document.head.appendChild(script);
+    document.head.removeChild(script);
+
+    // Check if it registered
+    if (isLanguageRegistered(code)) {
+      return { loaded: true };
+    }
+
+    return {
+      loaded: false,
+      error: `Script loaded but language '${code}' was not registered`,
+    };
+  } catch (error) {
+    return {
+      loaded: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/**
+ * Register a pre-loaded language module.
+ */
+export function registerLanguageModule(code: string, module: LanguageModule): void {
+  regLang(code, module.tokenizer, module.profile);
+
+  if (module.patterns) {
+    regPatterns(code, module.patterns);
+  } else if (module.buildPatterns) {
+    regPatterns(code, module.buildPatterns());
+  }
+}
+
+// =============================================================================
+// Type Helpers
+// =============================================================================
+
+export {
+  createSelector,
+  createLiteral,
+  createReference,
+  createPropertyPath,
+  createCommandNode,
+  createEventHandler,
+} from './types';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type {
+  ActionType,
+  SemanticRole,
+  SemanticValue,
+  SemanticNode,
+  LanguageToken,
+  TokenStream,
+} from './types';
+
+// =============================================================================
+// Pattern Generator (Optional)
+// =============================================================================
+// Note: This core bundle does NOT include the pattern generator by default.
+// Language bundles (e.g., browser-en.en.global.js) register their own patterns.
+// If you need dynamic pattern generation, import buildPatternsForLanguage from
+// the full bundle or use setPatternGenerator() to provide your own generator.