@lokascript/semantic 1.2.1 → 2.0.0

package/src/core-bridge.ts

@@ -14,6 +14,7 @@ import type {
   SemanticRole,
 } from './types';
 import { PatternMatcher } from './parser/pattern-matcher';
+import { parse as fullParse } from './parser/semantic-parser';
 import { getTokenizer } from './tokenizers';
 // Import from registry for tree-shaking (registry uses directly-registered patterns first)
 import { getPatternsForLanguage, getRegisteredLanguages } from './registry';
@@ -51,6 +52,11 @@ export interface SemanticAnalyzer {
   /**
    * Analyze input in the specified language.
    *
+   * @deprecated Since v1.4.0. Will be removed in v2.0.0.
+   * Prefer `parseSemantic()` from `@lokascript/semantic` for new code.
+   * This method is retained for backward compatibility but now uses the full
+   * parser internally to preserve event handler bodies.
+   *
    * @param input The input string to analyze
    * @param language ISO 639-1 language code
    * @returns Analysis result with confidence score
@@ -143,10 +149,34 @@ export class SemanticAnalyzerImpl implements SemanticAnalyzer {
 
   /**
    * Perform analysis without cache lookup.
+   *
+   * Uses full parser first to preserve complete AST structure (event handler
+   * bodies, compound statements, conditionals). Falls back to pattern matching
+   * only when the full parser fails, which provides fast simple-command detection
+   * but loses structural information like event handler bodies.
    */
   private analyzeUncached(input: string, language: string): SemanticAnalysisResult {
     try {
-      // Tokenize
+      // Try full parser first — this preserves event handler bodies,
+      // compound statements, and other structural information that
+      // pattern-only matching loses.
+      try {
+        const node = fullParse(input, language);
+        const result: SemanticAnalysisResult = {
+          confidence: node.metadata?.confidence ?? 0.8,
+          node,
+        };
+        if (node.kind === 'command') {
+          return { ...result, command: { name: node.action, roles: node.roles } };
+        }
+        return result;
+      } catch {
+        // Full parser failed — fall through to pattern matching
+      }
+
+      // Fallback: pattern matching for simple commands.
+      // This path is faster but only produces {kind: 'command'} nodes
+      // without structural information like event handler bodies.
       const tokenizer = getTokenizer(language);
       if (!tokenizer) {
         return {
@@ -157,7 +187,6 @@ export class SemanticAnalyzerImpl implements SemanticAnalyzer {
 
       const tokenStream = tokenizer.tokenize(input);
 
-      // Get patterns for this language
       const patterns = getPatternsForLanguage(language);
       if (patterns.length === 0) {
         return {
@@ -166,27 +195,25 @@ export class SemanticAnalyzerImpl implements SemanticAnalyzer {
         };
       }
 
-      // Try to match patterns
       const match = this.patternMatcher.matchBest(tokenStream, patterns);
 
-      if (!match) {
+      if (match) {
+        const node = this.buildSemanticNode(match);
+
         return {
-          confidence: 0,
-          errors: ['No pattern matched the input'],
+          confidence: match.confidence,
+          command: {
+            name: match.pattern.command,
+            roles: match.captured,
+          },
+          node,
+          tokensConsumed: match.consumedTokens,
         };
       }
 
-      // Build semantic node from match
-      const node = this.buildSemanticNode(match);
-
       return {
-        confidence: match.confidence,
-        command: {
-          name: match.pattern.command,
-          roles: match.captured,
-        },
-        node,
-        tokensConsumed: match.consumedTokens,
+        confidence: 0,
+        errors: ['No pattern matched the input'],
       };
     } catch (error) {
       return {

package/src/core.ts

@@ -148,6 +148,19 @@ export {
   createEventHandler,
 } from './types';
 
+// =============================================================================
+// Parsing & Rendering (registry-based, no language imports)
+// =============================================================================
+
+export { parse, canParse } from './parser';
+export { render, renderExplicit, translate, toExplicit, fromExplicit } from './explicit';
+
+// =============================================================================
+// Pattern Generation (for per-language bundles that need on-demand patterns)
+// =============================================================================
+
+export { generatePatternsForLanguage } from './generators/pattern-generator';
+
 // =============================================================================
 // Cache
 // =============================================================================

package/src/explicit/parser.ts

@@ -21,6 +21,7 @@ import {
   createSelector,
   createLiteral,
   createReference,
+  isValidReference,
 } from '../types';
 
 // =============================================================================
@@ -191,8 +192,9 @@ function parseExplicitValue(valueStr: string): SemanticValue {
   if (valueStr === 'false') return createLiteral(false, 'boolean');
 
   // Reference
-  if (['me', 'you', 'it', 'result', 'event', 'target', 'body'].includes(valueStr.toLowerCase())) {
-    return createReference(valueStr.toLowerCase() as any);
+  const lowerRef = valueStr.toLowerCase();
+  if (isValidReference(lowerRef)) {
+    return createReference(lowerRef);
   }
 
   // Number (possibly with duration suffix)

package/src/explicit/renderer.ts

@@ -129,7 +129,7 @@ export class SemanticRendererImpl implements ISemanticRenderer {
           if (node.roles.has(token.role)) {
             // Bonus for patterns that use roles we have
             score += 10;
-          } else if (!(token as any).optional) {
+          } else if (!token.optional) {
             // Heavy penalty for patterns that require roles we DON'T have
             // This prevents selecting "source" patterns when there's no source
             score -= 50;

package/src/generators/command-schemas.ts

@@ -5,7 +5,7 @@
  * Used by the pattern generator to create language-specific patterns.
  */
 
-import type { SemanticRole, ActionType, SemanticValue } from '../types';
+import type { SemanticRole, ActionType, SemanticValue, ExpectedType } from '../types';
 
 // =============================================================================
 // Command Schema Types
@@ -22,7 +22,7 @@ export interface RoleSpec {
   /** Whether this role is required */
   readonly required: boolean;
   /** Expected value types */
-  readonly expectedTypes: Array<'selector' | 'literal' | 'reference' | 'expression'>;
+  readonly expectedTypes: Array<ExpectedType>;
   /** Default value if not provided */
   readonly default?: SemanticValue;
   /** Position hint for SVO languages (higher = earlier) */
@@ -35,6 +35,13 @@ export interface RoleSpec {
    * If not specified, uses the language profile's default roleMarker.
    */
   readonly markerOverride?: Record<string, string>;
+  /**
+   * Override the rendering preposition for this role, separate from the parsing marker.
+   * Used when the parsing grammar differs from the rendered output
+   * (e.g., "go to /home" parses with 'to' but renders as "go /home").
+   * Maps language code to the rendering preposition.
+   */
+  readonly renderOverride?: Record<string, string>;
 }
 
 /**
@@ -174,6 +181,7 @@ export const addSchema: CommandSchema = {
       default: { type: 'reference', value: 'me' },
       svoPosition: 2,
       sovPosition: 1,
+      markerOverride: { en: 'to' }, // "add .class to #element"
     },
   ],
   // Runtime error documentation
@@ -263,6 +271,7 @@ export const putSchema: CommandSchema = {
       expectedTypes: ['selector', 'reference'],
       svoPosition: 2,
       sovPosition: 2, // SOV: destination comes second (に/에/a marker)
+      markerOverride: { en: 'into' }, // "put 'hello' into #output"
     },
   ],
   // Runtime error documentation
@@ -336,6 +345,10 @@ export const setSchema: CommandSchema = {
         ko: '를', // "x 를 10 으로 설정" - variable gets object marker
         tr: 'i', // "x i 10 e ayarla" - variable gets accusative marker
         ar: '', // "عيّن x إلى 10" - no marker before variable
+        sw: '', // "seti x kwenye 10" - no marker before variable
+        tl: '', // "itakda x sa 10" - no marker before variable
+        bn: 'কে', // "x কে 10 তে সেট" - patient marker on variable
+        qu: 'ta', // "x ta 10 man churay" - patient marker on variable
       },
     },
     {
@@ -359,6 +372,10 @@ export const setSchema: CommandSchema = {
         ko: '으로', // "x 를 10 으로 설정" - value gets manner/instrument marker
         tr: 'e', // "x i 10 e ayarla" - value gets dative marker
         ar: 'إلى', // "عيّن x إلى 10" - value gets preposition "to"
+        sw: 'kwenye', // "seti x kwenye 10" - destination prep before value
+        tl: 'sa', // "itakda x sa 10" - destination prep before value
+        bn: 'তে', // "x কে 10 তে সেট" - destination marker on value
+        qu: 'man', // "x ta 10 man churay" - destination marker on value
       },
     },
   ],
@@ -544,6 +561,8 @@ export const fetchSchema: CommandSchema = {
       expectedTypes: ['literal', 'expression'],
       svoPosition: 1,
       sovPosition: 1,
+      // No markerOverride — uses profile default 'from' for parsing.
+      renderOverride: { en: '' }, // "fetch /api" (rendering — no preposition)
     },
     {
       role: 'responseType',
@@ -597,6 +616,7 @@ export const incrementSchema: CommandSchema = {
       default: { type: 'literal', value: 1, dataType: 'number' },
       svoPosition: 2,
       sovPosition: 2,
+      markerOverride: { en: 'by' }, // "increment :count by 5"
     },
   ],
 };
@@ -626,6 +646,7 @@ export const decrementSchema: CommandSchema = {
       default: { type: 'literal', value: 1, dataType: 'number' },
       svoPosition: 2,
       sovPosition: 2,
+      markerOverride: { en: 'by' }, // "decrement :count by 5"
     },
   ],
 };
@@ -654,6 +675,7 @@ export const appendSchema: CommandSchema = {
       expectedTypes: ['selector', 'reference'],
       svoPosition: 2,
       sovPosition: 1,
+      markerOverride: { en: 'to' }, // "append <content> to #element"
     },
   ],
 };
@@ -682,6 +704,7 @@ export const prependSchema: CommandSchema = {
       expectedTypes: ['selector', 'reference'],
       svoPosition: 2,
       sovPosition: 1,
+      markerOverride: { en: 'to' }, // "prepend <content> to #element"
     },
   ],
 };
@@ -740,6 +763,10 @@ export const getCommandSchema: CommandSchema = {
         ar: 'على', // Arabic preposition: احصل على #element
         tr: 'i', // Turkish accusative: #element i al
         id: '',
+        sw: '', // Swahili SVO: pata #element (no marker)
+        tl: '', // Tagalog VSO: kunin #element (no marker)
+        bn: 'কে', // Bengali SOV: #element কে পান (patient marker)
+        qu: 'ta', // Quechua SOV: #element ta taripay (patient marker)
       },
     },
     {
@@ -1040,6 +1067,7 @@ export const forSchema: CommandSchema = {
       expectedTypes: ['selector', 'reference', 'expression'],
       svoPosition: 2,
       sovPosition: 1,
+      markerOverride: { en: 'in' }, // "for item in .items"
     },
   ],
 };
@@ -1096,6 +1124,8 @@ export const goSchema: CommandSchema = {
       expectedTypes: ['literal', 'expression'],
       svoPosition: 1,
       sovPosition: 1,
+      markerOverride: { en: 'to' }, // "go to /page" (parsing)
+      renderOverride: { en: '' }, // "go /page" (rendering — no preposition)
     },
   ],
 };
@@ -1116,6 +1146,9 @@ export const transitionSchema: CommandSchema = {
       expectedTypes: ['literal'], // Only literal - CSS properties are strings, not selectors
       svoPosition: 1,
       sovPosition: 2,
+      // No marker before the CSS property name (SVO/VSO languages)
+      // SOV languages (bn, qu) use their default patient marker from profile
+      markerOverride: { en: '', ar: '', tl: '', sw: '' },
     },
     {
       role: 'goal',
@@ -1124,6 +1157,23 @@ export const transitionSchema: CommandSchema = {
       expectedTypes: ['literal', 'expression'],
       svoPosition: 2,
       sovPosition: 3,
+      // "to" preposition before goal value (same as set's patient marker)
+      markerOverride: {
+        en: 'to',
+        ar: 'إلى',
+        tl: 'sa',
+        sw: 'kwenye',
+        bn: 'তে',
+        qu: 'man',
+        es: 'a',
+        pt: 'para',
+        fr: 'à',
+        de: 'auf',
+        ja: 'に',
+        ko: '으로',
+        tr: 'e',
+        id: 'ke',
+      },
     },
     {
       role: 'destination',
@@ -1141,6 +1191,7 @@ export const transitionSchema: CommandSchema = {
       expectedTypes: ['literal'],
       svoPosition: 4,
       sovPosition: 4,
+      markerOverride: { en: 'over' }, // "transition opacity to 1 over 500ms"
     },
     {
       role: 'style',
@@ -1177,6 +1228,7 @@ export const cloneSchema: CommandSchema = {
       expectedTypes: ['selector', 'reference'],
       svoPosition: 2,
       sovPosition: 1,
+      markerOverride: { en: 'into' }, // "clone #element into #container"
     },
   ],
 };
@@ -1317,6 +1369,7 @@ export const tellSchema: CommandSchema = {
       expectedTypes: ['selector', 'reference'],
       svoPosition: 1,
       sovPosition: 1,
+      markerOverride: { en: '' }, // "tell #element ..." (no preposition)
     },
   ],
 };
@@ -1337,6 +1390,15 @@ export const defaultSchema: CommandSchema = {
       expectedTypes: ['reference'],
       svoPosition: 1,
       sovPosition: 1,
+      // Same overrides as SET: no marker before variable in VSO/SVO
+      markerOverride: {
+        en: '',
+        ar: '',
+        tl: '',
+        sw: '',
+        bn: 'কে',
+        qu: 'ta',
+      },
     },
     {
       role: 'patient',
@@ -1345,6 +1407,15 @@ export const defaultSchema: CommandSchema = {
       expectedTypes: ['literal', 'expression'],
       svoPosition: 2,
       sovPosition: 2,
+      // Same overrides as SET: value gets destination preposition
+      markerOverride: {
+        en: 'to',
+        ar: 'إلى',
+        tl: 'sa',
+        sw: 'kwenye',
+        bn: 'তে',
+        qu: 'man',
+      },
     },
   ],
 };
@@ -1447,6 +1518,7 @@ export const measureSchema: CommandSchema = {
       default: { type: 'reference', value: 'me' },
       svoPosition: 2,
       sovPosition: 2,
+      markerOverride: { en: 'of' }, // "measure width of #element"
     },
   ],
 };
@@ -1476,6 +1548,7 @@ export const swapSchema: CommandSchema = {
       expectedTypes: ['literal'],
       svoPosition: 1,
       sovPosition: 3,
+      markerOverride: { en: '' }, // "swap innerHTML ..." (no preposition)
     },
     {
       role: 'destination',
@@ -1484,6 +1557,7 @@ export const swapSchema: CommandSchema = {
       expectedTypes: ['selector', 'reference'],
       svoPosition: 2,
       sovPosition: 1,
+      markerOverride: { en: 'of' }, // "swap innerHTML of #target"
     },
     {
       role: 'patient',
@@ -1492,6 +1566,7 @@ export const swapSchema: CommandSchema = {
       expectedTypes: ['literal', 'expression', 'selector'],
       svoPosition: 3,
       sovPosition: 2,
+      markerOverride: { en: 'with' }, // "swap innerHTML of #target with <html>"
     },
   ],
 };
@@ -1516,6 +1591,7 @@ export const morphSchema: CommandSchema = {
       expectedTypes: ['selector', 'reference'],
       svoPosition: 1,
       sovPosition: 1,
+      markerOverride: { en: '' }, // "morph #target ..." (no preposition)
     },
     {
       role: 'patient',
@@ -1524,6 +1600,135 @@ export const morphSchema: CommandSchema = {
       expectedTypes: ['literal', 'expression', 'selector'],
       svoPosition: 2,
       sovPosition: 2,
+      markerOverride: { en: 'to' }, // "morph #target to <html>"
+    },
+  ],
+};
+
+// =============================================================================
+// Batch 6 - Missing Commands (beep, break, copy, exit, pick, render)
+// =============================================================================
+
+/**
+ * Beep command: debug output with type information.
+ * Syntax: beep! / beep! <expression>
+ */
+export const beepSchema: CommandSchema = {
+  action: 'beep',
+  description: 'Debug output for expressions with type information',
+  category: 'variable',
+  primaryRole: 'patient',
+  roles: [
+    {
+      role: 'patient',
+      description: 'The expression(s) to debug',
+      required: false,
+      expectedTypes: ['literal', 'selector', 'reference', 'expression'],
+      svoPosition: 1,
+      sovPosition: 1,
+    },
+  ],
+};
+
+/**
+ * Break command: exits from the current loop.
+ * Syntax: break
+ */
+export const breakSchema: CommandSchema = {
+  action: 'break',
+  description: 'Exit from the current loop',
+  category: 'control-flow',
+  primaryRole: 'patient',
+  roles: [],
+};
+
+/**
+ * Copy command: copies text or element content to clipboard.
+ * Syntax: copy <source>
+ */
+export const copySchema: CommandSchema = {
+  action: 'copy',
+  description: 'Copy text or element content to the clipboard',
+  category: 'dom-content',
+  primaryRole: 'patient',
+  roles: [
+    {
+      role: 'patient',
+      description: 'The text or element to copy',
+      required: true,
+      expectedTypes: ['literal', 'selector', 'reference', 'expression'],
+      svoPosition: 1,
+      sovPosition: 1,
+    },
+  ],
+};
+
+/**
+ * Exit command: exits early from an event handler.
+ * Syntax: exit
+ */
+export const exitSchema: CommandSchema = {
+  action: 'exit',
+  description: 'Exit from the current event handler',
+  category: 'control-flow',
+  primaryRole: 'patient',
+  roles: [],
+};
+
+/**
+ * Pick command: selects a random element from a collection.
+ * Syntax: pick <item1>, <item2>, ... / pick from <array>
+ */
+export const pickSchema: CommandSchema = {
+  action: 'pick',
+  description: 'Select a random element from a collection',
+  category: 'variable',
+  primaryRole: 'patient',
+  roles: [
+    {
+      role: 'patient',
+      description: 'The items to pick from',
+      required: true,
+      expectedTypes: ['literal', 'expression', 'reference'],
+      svoPosition: 1,
+      sovPosition: 1,
+    },
+    {
+      role: 'source',
+      description: 'The array to pick from (with "from" keyword)',
+      required: false,
+      expectedTypes: ['reference', 'expression'],
+      svoPosition: 2,
+      sovPosition: 2,
+    },
+  ],
+};
+
+/**
+ * Render command: renders a template with variables.
+ * Syntax: render <template> / render <template> with <variables>
+ */
+export const renderSchema: CommandSchema = {
+  action: 'render',
+  description: 'Render a template with optional variables',
+  category: 'dom-content',
+  primaryRole: 'patient',
+  roles: [
+    {
+      role: 'patient',
+      description: 'The template to render',
+      required: true,
+      expectedTypes: ['selector', 'reference', 'expression'],
+      svoPosition: 1,
+      sovPosition: 2,
+    },
+    {
+      role: 'style',
+      description: 'Variables to pass to the template (with keyword)',
+      required: false,
+      expectedTypes: ['expression', 'reference'],
+      svoPosition: 2,
+      sovPosition: 1,
     },
   ],
 };
@@ -1589,6 +1794,13 @@ export const commandSchemas: Record<ActionType, CommandSchema> = {
   // Batch 5 - DOM Content Manipulation
   swap: swapSchema,
   morph: morphSchema,
+  // Batch 6 - Missing Commands
+  beep: beepSchema,
+  break: breakSchema,
+  copy: copySchema,
+  exit: exitSchema,
+  pick: pickSchema,
+  render: renderSchema,
   // Meta commands (for compound structures)
   compound: {
     action: 'compound',