@lokascript/framework 2.0.0

package/dist/core/pattern-matching/index.js

@@ -0,0 +1,1239 @@
+// src/core/types.ts
+function createLiteral(value, dataType) {
+  return dataType ? { type: "literal", value, dataType } : { type: "literal", value };
+}
+function createSelector(value, selectorKind) {
+  return selectorKind ? { type: "selector", value, selectorKind } : { type: "selector", value };
+}
+function createReference(value) {
+  return { type: "reference", value };
+}
+function createPropertyPath(object, property) {
+  return { type: "property-path", object, property };
+}
+
+// src/core/logger.ts
+var DebugLogger = class {
+  constructor(namespace) {
+    this.namespace = namespace;
+    this.enabled = this.checkEnabled();
+  }
+  checkEnabled() {
+    if (typeof process !== "undefined" && process.env) {
+      const DEBUG = process.env.DEBUG || "";
+      return DEBUG === "*" || DEBUG.includes("framework:*") || DEBUG.includes(`framework:${this.namespace}`);
+    }
+    return false;
+  }
+  log(level, message, ...args) {
+    if (!this.enabled) return;
+    const prefix = `[framework:${this.namespace}]`;
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    switch (level) {
+      case "debug":
+        console.debug(`${timestamp} ${prefix} DEBUG:`, message, ...args);
+        break;
+      case "info":
+        console.info(`${timestamp} ${prefix} INFO:`, message, ...args);
+        break;
+      case "warn":
+        console.warn(`${timestamp} ${prefix} WARN:`, message, ...args);
+        break;
+      case "error":
+        console.error(`${timestamp} ${prefix} ERROR:`, message, ...args);
+        break;
+    }
+  }
+  debug(message, ...args) {
+    this.log("debug", message, ...args);
+  }
+  info(message, ...args) {
+    this.log("info", message, ...args);
+  }
+  warn(message, ...args) {
+    this.log("warn", message, ...args);
+  }
+  error(message, ...args) {
+    this.log("error", message, ...args);
+  }
+  /**
+   * Check if logging is enabled for this namespace.
+   */
+  isEnabled() {
+    return this.enabled;
+  }
+  /**
+   * Programmatically enable logging for this namespace.
+   */
+  enable() {
+    this.enabled = true;
+  }
+  /**
+   * Programmatically disable logging for this namespace.
+   */
+  disable() {
+    this.enabled = false;
+  }
+};
+function createLogger(namespace) {
+  return new DebugLogger(namespace);
+}
+
+// src/core/pattern-matching/utils/type-validation.ts
+function isTypeCompatible(actualType, expectedTypes) {
+  if (!expectedTypes || expectedTypes.length === 0) {
+    return true;
+  }
+  if (expectedTypes.includes(actualType)) {
+    return true;
+  }
+  if (expectedTypes.includes("expression")) {
+    return true;
+  }
+  if (actualType === "property-path") {
+    return expectedTypes.some((t) => ["selector", "reference", "expression"].includes(t));
+  }
+  return false;
+}
+function validateValueType(value, expectedTypes) {
+  if (!expectedTypes || expectedTypes.length === 0) {
+    return true;
+  }
+  return isTypeCompatible(value.type, expectedTypes);
+}
+function isCSSSelector(value) {
+  return value.startsWith(".") || value.startsWith("#") || value.startsWith("<");
+}
+function isClassName(value) {
+  return value.startsWith(".");
+}
+function isIdSelector(value) {
+  return value.startsWith("#");
+}
+function isCSSPropertyRef(value) {
+  return value.startsWith("*");
+}
+function isNumericValue(value) {
+  const durationMatch = value.match(/^(\d+(?:\.\d+)?)(ms|s|m|h)?$/);
+  if (durationMatch) {
+    return true;
+  }
+  const num = parseFloat(value);
+  return !isNaN(num) && isFinite(num);
+}
+function isPropertyName(value) {
+  return /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(value);
+}
+function isVariableRef(value) {
+  return value.startsWith(":");
+}
+function isBuiltInReference(value) {
+  const builtIns = /* @__PURE__ */ new Set(["me", "you", "it", "result", "event", "target", "body"]);
+  return builtIns.has(value.toLowerCase());
+}
+
+// src/core/pattern-matching/utils/possessive-keywords.ts
+function getPossessiveReference(profile, keyword) {
+  return profile?.possessive?.keywords?.[keyword];
+}
+function isPossessiveKeyword(profile, keyword) {
+  return profile?.possessive?.keywords?.[keyword] !== void 0;
+}
+function getAllPossessiveKeywords(profile) {
+  return profile?.possessive?.keywords ?? {};
+}
+
+// src/core/pattern-matching/pattern-matcher.ts
+function isValidReference(_value) {
+  return false;
+}
+var _PatternMatcher = class _PatternMatcher {
+  constructor() {
+    /** Debug logger */
+    this.logger = createLogger("pattern-matcher");
+    /**
+     * Track stem matches for confidence calculation.
+     * This is set during matching and read during confidence calculation.
+     */
+    this.stemMatchCount = 0;
+    this.totalKeywordMatches = 0;
+  }
+  /**
+   * Safely convert a value to lowercase string.
+   * Provides protection against non-string values at runtime.
+   */
+  safeToLowerCase(value) {
+    if (typeof value === "string") {
+      return value.toLowerCase();
+    }
+    if (value === null || value === void 0) {
+      return "";
+    }
+    return String(value).toLowerCase();
+  }
+  /**
+   * Try to match a single pattern against the token stream.
+   * Returns the match result or null if no match.
+   *
+   * @param tokens - Token stream to match against
+   * @param pattern - Pattern to match
+   * @param profile - Optional language profile for possessive handling
+   */
+  matchPattern(tokens, pattern, profile) {
+    const mark = tokens.mark();
+    const captured = /* @__PURE__ */ new Map();
+    this.logger.debug("========================================");
+    this.logger.debug("matchPattern ENTRY");
+    this.logger.debug("Pattern ID:", pattern.id);
+    this.logger.debug("Pattern command:", pattern.command);
+    this.logger.debug("Pattern language:", pattern.language);
+    this.logger.debug("Pattern template:", JSON.stringify(pattern.template, null, 2));
+    if (this.logger.isEnabled()) {
+      const firstTokens = [];
+      for (let i = 0; i < 10; i++) {
+        const t = tokens.peek(i);
+        if (t)
+          firstTokens.push({
+            type: t.type,
+            value: t.value,
+            kind: t.kind
+          });
+        else break;
+      }
+      this.logger.debug("Input tokens (first 10):", firstTokens);
+      this.logger.debug("Profile code:", profile?.code);
+    }
+    this.currentProfile = profile;
+    this.stemMatchCount = 0;
+    this.totalKeywordMatches = 0;
+    this.logger.debug("--- Calling matchTokenSequence ---");
+    this.logger.debug("Pattern tokens to match:", JSON.stringify(pattern.template.tokens, null, 2));
+    const success = this.matchTokenSequence(tokens, pattern.template.tokens, captured);
+    this.logger.debug("matchTokenSequence returned:", success);
+    this.logger.debug(
+      "Captured roles:",
+      Array.from(captured.entries()).map(([k, v]) => [k, JSON.stringify(v)])
+    );
+    if (!success) {
+      this.logger.debug(">>> MATCH FAILED - resetting token position");
+      tokens.reset(mark);
+      return null;
+    }
+    const confidence = this.calculateConfidence(pattern, captured);
+    this.applyExtractionRules(pattern, captured);
+    return {
+      pattern,
+      captured,
+      consumedTokens: tokens.position() - mark.position,
+      confidence
+    };
+  }
+  /**
+   * Try to match multiple patterns, return the best match.
+   *
+   * @param tokens - Token stream to match against
+   * @param patterns - Candidate patterns to try
+   * @param profile - Optional language profile for possessive handling
+   */
+  matchBest(tokens, patterns, profile) {
+    const matches = [];
+    for (const pattern of patterns) {
+      const mark = tokens.mark();
+      const result = this.matchPattern(tokens, pattern, profile);
+      if (result) {
+        matches.push(result);
+      }
+      tokens.reset(mark);
+    }
+    if (matches.length === 0) {
+      return null;
+    }
+    matches.sort((a, b) => {
+      const priorityDiff = b.pattern.priority - a.pattern.priority;
+      if (priorityDiff !== 0) return priorityDiff;
+      const confidenceDiff = b.confidence - a.confidence;
+      if (Math.abs(confidenceDiff) > 1e-3) return confidenceDiff;
+      return b.consumedTokens - a.consumedTokens;
+    });
+    const best = matches[0];
+    this.matchPattern(tokens, best.pattern);
+    return best;
+  }
+  /**
+   * Match a sequence of pattern tokens against the token stream.
+   *
+   * Supports bounded single-step backtracking: if an optional role consumes
+   * a token and the immediately following pattern token fails, the matcher
+   * resets to before the optional role and retries the failed token.
+   */
+  matchTokenSequence(tokens, patternTokens, captured) {
+    const firstPatternToken = patternTokens[0];
+    const patternExpectsConjunction = firstPatternToken?.type === "literal" && (firstPatternToken.value === "and" || firstPatternToken.value === "then" || firstPatternToken.alternatives?.includes("and") || firstPatternToken.alternatives?.includes("then"));
+    if (this.currentProfile?.code === "ar" && !patternExpectsConjunction) {
+      while (tokens.peek()?.kind === "conjunction") {
+        tokens.advance();
+      }
+    }
+    let prevOptionalMark = null;
+    let prevOptionalRole = null;
+    for (let i = 0; i < patternTokens.length; i++) {
+      const patternToken = patternTokens[i];
+      this.logger.debug("  >> Matching pattern token:", JSON.stringify(patternToken, null, 2));
+      const currTok = tokens.peek();
+      this.logger.debug(
+        "  >> Current input token:",
+        currTok ? JSON.stringify({
+          type: currTok.type,
+          value: currTok.value,
+          kind: currTok.kind
+        }) : "EOF"
+      );
+      if (patternToken.type === "role" && patternToken.greedy) {
+        const stopMarkers = this.collectStopMarkers(patternTokens, i + 1);
+        const values = [];
+        while (!tokens.isAtEnd()) {
+          const nextToken = tokens.peek();
+          if (!nextToken) break;
+          if (this.isStopMarker(nextToken, stopMarkers)) break;
+          values.push(nextToken.value);
+          tokens.advance();
+        }
+        if (values.length > 0) {
+          captured.set(patternToken.role, { type: "expression", raw: values.join(" ") });
+          prevOptionalMark = null;
+          prevOptionalRole = null;
+          continue;
+        } else if (patternToken.optional) {
+          continue;
+        } else {
+          return false;
+        }
+      }
+      const isOptionalRole = patternToken.type === "role" && patternToken.optional === true;
+      const markBefore = isOptionalRole ? tokens.mark() : null;
+      const matched = this.matchPatternToken(tokens, patternToken, captured);
+      this.logger.debug("  >> Match result:", matched);
+      if (matched) {
+        if (isOptionalRole) {
+          prevOptionalMark = markBefore;
+          prevOptionalRole = patternToken.role;
+        } else {
+          prevOptionalMark = null;
+          prevOptionalRole = null;
+        }
+        continue;
+      }
+      this.logger.debug("  >> Token match FAILED");
+      if (this.isOptional(patternToken)) {
+        continue;
+      }
+      if (prevOptionalMark && prevOptionalRole) {
+        this.logger.debug("  >> BACKTRACKING: undoing optional role", prevOptionalRole);
+        tokens.reset(prevOptionalMark);
+        captured.delete(prevOptionalRole);
+        prevOptionalMark = null;
+        prevOptionalRole = null;
+        const retryMatched = this.matchPatternToken(tokens, patternToken, captured);
+        this.logger.debug("  >> Backtrack retry result:", retryMatched);
+        if (retryMatched) {
+          continue;
+        }
+      }
+      return false;
+    }
+    return true;
+  }
+  /**
+   * Match a single pattern token against the current position in the stream.
+   */
+  matchPatternToken(tokens, patternToken, captured) {
+    switch (patternToken.type) {
+      case "literal":
+        return this.matchLiteralToken(tokens, patternToken);
+      case "role":
+        return this.matchRoleToken(tokens, patternToken, captured);
+      case "group":
+        return this.matchGroupToken(tokens, patternToken, captured);
+      default:
+        return false;
+    }
+  }
+  /**
+   * Match a literal pattern token (keyword or particle).
+   */
+  matchLiteralToken(tokens, patternToken) {
+    const token = tokens.peek();
+    this.logger.debug("    >>> matchLiteralToken: expecting", patternToken.value);
+    this.logger.debug(
+      "    >>> matchLiteralToken: got token",
+      token ? JSON.stringify({
+        type: token.type,
+        value: token.value,
+        kind: token.kind
+      }) : "null"
+    );
+    if (!token) {
+      this.logger.debug("    >>> matchLiteralToken: FAIL - no token");
+      return false;
+    }
+    const matchType = this.getMatchType(token, patternToken.value);
+    this.logger.debug(
+      "    >>> matchType for",
+      token.value,
+      "vs",
+      patternToken.value,
+      ":",
+      matchType
+    );
+    if (matchType !== "none") {
+      this.totalKeywordMatches++;
+      if (matchType === "stem") {
+        this.stemMatchCount++;
+      }
+      tokens.advance();
+      return true;
+    }
+    if (patternToken.alternatives) {
+      for (const alt of patternToken.alternatives) {
+        const altMatchType = this.getMatchType(token, alt);
+        if (altMatchType !== "none") {
+          this.totalKeywordMatches++;
+          if (altMatchType === "stem") {
+            this.stemMatchCount++;
+          }
+          tokens.advance();
+          return true;
+        }
+      }
+    }
+    return false;
+  }
+  /**
+   * Match a role pattern token (captures a semantic value).
+   * Handles multi-token expressions like:
+   * - 'my value' (possessive keyword + property)
+   * - '#dialog.showModal()' (method call)
+   * - "#element's *opacity" (possessive selector + property)
+   */
+  matchRoleToken(tokens, patternToken, captured) {
+    this.logger.debug("    >>> matchRoleToken ENTRY: capturing role", patternToken.role);
+    this.logger.debug("    >>> matchRoleToken: expected types", patternToken.expectedTypes);
+    this.logger.debug("    >>> matchRoleToken: optional?", patternToken.optional);
+    this.skipNoiseWords(tokens);
+    const token = tokens.peek();
+    this.logger.debug(
+      "    >>> After skipNoiseWords, current token:",
+      token ? JSON.stringify({ value: token.value, kind: token.kind }) : "null"
+    );
+    if (!token) {
+      return patternToken.optional || false;
+    }
+    const possessiveValue = this.tryMatchPossessiveExpression(tokens);
+    if (possessiveValue) {
+      if (patternToken.expectedTypes && patternToken.expectedTypes.length > 0) {
+        if (!patternToken.expectedTypes.includes(possessiveValue.type) && !patternToken.expectedTypes.includes("expression")) {
+          return patternToken.optional || false;
+        }
+      }
+      captured.set(patternToken.role, possessiveValue);
+      return true;
+    }
+    const methodCallValue = this.tryMatchMethodCallExpression(tokens);
+    if (methodCallValue) {
+      if (patternToken.expectedTypes && patternToken.expectedTypes.length > 0) {
+        if (!patternToken.expectedTypes.includes(methodCallValue.type) && !patternToken.expectedTypes.includes("expression")) {
+          return patternToken.optional || false;
+        }
+      }
+      captured.set(patternToken.role, methodCallValue);
+      return true;
+    }
+    const possessiveSelectorValue = this.tryMatchPossessiveSelectorExpression(tokens);
+    if (possessiveSelectorValue) {
+      if (patternToken.expectedTypes && patternToken.expectedTypes.length > 0) {
+        if (!isTypeCompatible(possessiveSelectorValue.type, patternToken.expectedTypes)) {
+          return patternToken.optional || false;
+        }
+      }
+      captured.set(patternToken.role, possessiveSelectorValue);
+      return true;
+    }
+    const propertyAccessValue = this.tryMatchPropertyAccessExpression(tokens);
+    if (propertyAccessValue) {
+      if (patternToken.expectedTypes && patternToken.expectedTypes.length > 0) {
+        if (!patternToken.expectedTypes.includes(propertyAccessValue.type) && !patternToken.expectedTypes.includes("expression")) {
+          return patternToken.optional || false;
+        }
+      }
+      captured.set(patternToken.role, propertyAccessValue);
+      return true;
+    }
+    const selectorPropertyValue = this.tryMatchSelectorPropertyExpression(tokens);
+    if (selectorPropertyValue) {
+      if (patternToken.expectedTypes && patternToken.expectedTypes.length > 0) {
+        if (!isTypeCompatible(selectorPropertyValue.type, patternToken.expectedTypes)) {
+          return patternToken.optional || false;
+        }
+      }
+      captured.set(patternToken.role, selectorPropertyValue);
+      return true;
+    }
+    this.logger.debug(
+      "    >>> Trying tokenToSemanticValue for token:",
+      token ? JSON.stringify({ value: token.value, kind: token.kind }) : "null"
+    );
+    const value = this.tokenToSemanticValue(token);
+    this.logger.debug(
+      "    >>> tokenToSemanticValue returned:",
+      value ? JSON.stringify(value) : "null"
+    );
+    if (!value) {
+      return patternToken.optional || false;
+    }
+    this.logger.debug(
+      "    >>> Validating type:",
+      value.type,
+      "against expected:",
+      patternToken.expectedTypes
+    );
+    if (patternToken.expectedTypes && patternToken.expectedTypes.length > 0) {
+      if (!isTypeCompatible(value.type, patternToken.expectedTypes)) {
+        this.logger.debug("    >>> TYPE MISMATCH - returning", patternToken.optional || false);
+        return patternToken.optional || false;
+      }
+    }
+    this.logger.debug("    >>> Type validation PASSED");
+    captured.set(patternToken.role, value);
+    tokens.advance();
+    return true;
+  }
+  /**
+   * Try to match a possessive expression like 'my value' or 'its innerHTML'.
+   * Returns the PropertyPathValue if matched, or null if not.
+   */
+  tryMatchPossessiveExpression(tokens) {
+    const token = tokens.peek();
+    if (!token) return null;
+    if (!this.currentProfile) return null;
+    const tokenValue = token.normalized || token.value;
+    const tokenLower = this.safeToLowerCase(tokenValue);
+    const baseRef = getPossessiveReference(this.currentProfile, tokenLower);
+    if (!baseRef) return null;
+    const mark = tokens.mark();
+    tokens.advance();
+    const propertyToken = tokens.peek();
+    if (!propertyToken) {
+      tokens.reset(mark);
+      return null;
+    }
+    if (propertyToken.kind === "identifier" || propertyToken.kind === "keyword" && !this.isStructuralKeyword(propertyToken.value) || propertyToken.kind === "selector" && propertyToken.value.startsWith("*") || propertyToken.kind === "selector" && propertyToken.value.startsWith("@") || propertyToken.kind === "selector" && propertyToken.value.startsWith(".") && /^\.[a-zA-Z_]\w*/.test(propertyToken.value)) {
+      tokens.advance();
+      let propertyName = propertyToken.value;
+      if (propertyToken.kind === "selector" && propertyName.startsWith(".") && /^\.[a-zA-Z_]\w*/.test(propertyName)) {
+        propertyName = propertyName.substring(1);
+      }
+      let chainedProps = propertyName;
+      while (tokens.peek()?.kind === "selector" && tokens.peek().value.startsWith(".") && /^\.[a-zA-Z_]\w*/.test(tokens.peek().value)) {
+        chainedProps += tokens.peek().value;
+        tokens.advance();
+      }
+      const nextPeek = tokens.peek();
+      if (nextPeek?.kind === "literal" && nextPeek.value.startsWith("(")) {
+        chainedProps += nextPeek.value;
+        tokens.advance();
+      }
+      return createPropertyPath(createReference(baseRef), chainedProps);
+    }
+    tokens.reset(mark);
+    return null;
+  }
+  /**
+   * Check if a keyword is a structural keyword (preposition, control flow, etc.)
+   * that shouldn't be consumed as a property name.
+   */
+  isStructuralKeyword(value) {
+    const structural = /* @__PURE__ */ new Set([
+      // Prepositions
+      "into",
+      "in",
+      "to",
+      "from",
+      "at",
+      "by",
+      "with",
+      "without",
+      "before",
+      "after",
+      "of",
+      "as",
+      "on",
+      // Control flow
+      "then",
+      "end",
+      "else",
+      "if",
+      "repeat",
+      "while",
+      "for",
+      // Commands (shouldn't be property names)
+      "toggle",
+      "add",
+      "remove",
+      "put",
+      "set",
+      "show",
+      "hide",
+      "increment",
+      "decrement",
+      "send",
+      "trigger",
+      "call"
+    ]);
+    return structural.has(value.toLowerCase());
+  }
+  /**
+   * Try to match a method call expression like '#dialog.showModal()'.
+   * Pattern: selector + '.' + identifier + '(' + [args] + ')'
+   * Returns an expression value if matched, or null if not.
+   */
+  tryMatchMethodCallExpression(tokens) {
+    const token = tokens.peek();
+    if (!token || token.kind !== "selector") return null;
+    const mark = tokens.mark();
+    tokens.advance();
+    const dotToken = tokens.peek();
+    if (!dotToken || dotToken.kind !== "operator" || dotToken.value !== ".") {
+      tokens.reset(mark);
+      return null;
+    }
+    tokens.advance();
+    const methodToken = tokens.peek();
+    if (!methodToken || methodToken.kind !== "identifier") {
+      tokens.reset(mark);
+      return null;
+    }
+    tokens.advance();
+    const openParen = tokens.peek();
+    if (!openParen || openParen.kind !== "punctuation" || openParen.value !== "(") {
+      tokens.reset(mark);
+      return null;
+    }
+    tokens.advance();
+    const args = [];
+    while (!tokens.isAtEnd() && args.length < _PatternMatcher.MAX_METHOD_ARGS) {
+      const argToken = tokens.peek();
+      if (!argToken) break;
+      if (argToken.kind === "punctuation" && argToken.value === ")") {
+        tokens.advance();
+        break;
+      }
+      if (argToken.kind === "punctuation" && argToken.value === ",") {
+        tokens.advance();
+        continue;
+      }
+      args.push(argToken.value);
+      tokens.advance();
+    }
+    const methodCall = `${token.value}.${methodToken.value}(${args.join(", ")})`;
+    return {
+      type: "expression",
+      raw: methodCall
+    };
+  }
+  /**
+   * Try to match a property access expression like 'userData.name' or 'it.data'.
+   * Pattern: (identifier | keyword) + '.' + identifier [+ '.' + identifier ...]
+   * Returns an expression value if matched, or null if not.
+   */
+  tryMatchPropertyAccessExpression(tokens) {
+    const token = tokens.peek();
+    if (!token) return null;
+    if (token.kind !== "identifier" && token.kind !== "keyword") return null;
+    const mark = tokens.mark();
+    tokens.advance();
+    const dotToken = tokens.peek();
+    if (!dotToken || dotToken.kind !== "operator" || dotToken.value !== ".") {
+      tokens.reset(mark);
+      return null;
+    }
+    tokens.advance();
+    const propertyToken = tokens.peek();
+    if (!propertyToken || propertyToken.kind !== "identifier") {
+      tokens.reset(mark);
+      return null;
+    }
+    tokens.advance();
+    let chain = `${token.value}.${propertyToken.value}`;
+    let depth = 1;
+    while (!tokens.isAtEnd() && depth < _PatternMatcher.MAX_PROPERTY_DEPTH) {
+      const nextDot = tokens.peek();
+      if (!nextDot || nextDot.kind !== "operator" || nextDot.value !== ".") {
+        break;
+      }
+      tokens.advance();
+      const nextProp = tokens.peek();
+      if (!nextProp || nextProp.kind !== "identifier") {
+        break;
+      }
+      tokens.advance();
+      chain += `.${nextProp.value}`;
+      depth++;
+    }
+    const openParen = tokens.peek();
+    if (openParen && openParen.kind === "punctuation" && openParen.value === "(") {
+      tokens.advance();
+      const args = [];
+      let argDepth = 0;
+      while (!tokens.isAtEnd() && args.length < _PatternMatcher.MAX_METHOD_ARGS) {
+        const argToken = tokens.peek();
+        if (!argToken) break;
+        if (argToken.kind === "punctuation" && argToken.value === ")") {
+          if (argDepth === 0) {
+            tokens.advance();
+            break;
+          }
+          argDepth--;
+        }
+        if (argToken.kind === "punctuation" && argToken.value === "(") {
+          argDepth++;
+        }
+        if (argToken.kind === "punctuation" && argToken.value === ",") {
+          tokens.advance();
+          continue;
+        }
+        args.push(argToken.value);
+        tokens.advance();
+      }
+      const methodCall = `${chain}(${args.join(", ")})`;
+      return {
+        type: "expression",
+        raw: methodCall
+      };
+    }
+    return {
+      type: "expression",
+      raw: chain
+    };
+  }
+  /**
+   * Try to match a possessive selector expression like "#element's *opacity".
+   * Pattern: selector + "'s" + (selector | identifier)
+   * Returns a property-path value if matched, or null if not.
+   */
+  tryMatchPossessiveSelectorExpression(tokens) {
+    const token = tokens.peek();
+    if (!token || token.kind !== "selector") return null;
+    const mark = tokens.mark();
+    tokens.advance();
+    const possessiveToken = tokens.peek();
+    if (!possessiveToken || possessiveToken.kind !== "punctuation" || possessiveToken.value !== "'s") {
+      tokens.reset(mark);
+      return null;
+    }
+    tokens.advance();
+    const propertyToken = tokens.peek();
+    if (!propertyToken) {
+      tokens.reset(mark);
+      return null;
+    }
+    if (propertyToken.kind !== "selector" && propertyToken.kind !== "identifier") {
+      tokens.reset(mark);
+      return null;
+    }
+    tokens.advance();
+    return createPropertyPath(createSelector(token.value), propertyToken.value);
+  }
+  /**
+   * Try to match a selector + property expression like "#output.innerText".
+   * This handles cases where the tokenizer produces two selector tokens:
+   * - #output (id selector)
+   * - .innerText (looks like class selector, but is actually property)
+   *
+   * Pattern: id-selector + class-selector-that-is-actually-property
+   * Returns a property-path value if matched, or null if not.
+   */
+  tryMatchSelectorPropertyExpression(tokens) {
+    const token = tokens.peek();
+    if (!token || token.kind !== "selector") return null;
+    if (typeof token.value !== "string" || !token.value.startsWith("#")) return null;
+    const mark = tokens.mark();
+    tokens.advance();
+    const propertyToken = tokens.peek();
+    if (!propertyToken || propertyToken.kind !== "selector") {
+      tokens.reset(mark);
+      return null;
+    }
+    if (!propertyToken.value.startsWith(".")) {
+      tokens.reset(mark);
+      return null;
+    }
+    const peek2 = tokens.peek(1);
+    if (peek2 && peek2.kind === "selector") {
+    }
+    tokens.advance();
+    const propertyName = propertyToken.value.slice(1);
+    return createPropertyPath(createSelector(token.value), propertyName);
+  }
+  /**
+   * Match a group pattern token (optional sequence).
+   * When the group's leading marker isn't at the current position, scans ahead
+   * up to MAX_MARKER_SCAN tokens to find it. This allows unmarked tokens
+   * (e.g., a value like 'hello') to sit between groups without blocking later
+   * marker matches.
+   */
+  matchGroupToken(tokens, patternToken, captured) {
+    const mark = tokens.mark();
+    const capturedBefore = new Set(captured.keys());
+    const success = this.matchTokenSequence(tokens, patternToken.tokens, captured);
+    if (success) return true;
+    tokens.reset(mark);
+    for (const role of captured.keys()) {
+      if (!capturedBefore.has(role)) captured.delete(role);
+    }
+    if (!patternToken.optional) return false;
+    const leadingMarker = this.getGroupLeadingMarker(patternToken);
+    if (leadingMarker) {
+      for (let offset = 1; offset <= _PatternMatcher.MAX_MARKER_SCAN; offset++) {
+        const ahead = tokens.peek(offset);
+        if (!ahead) break;
+        const aheadValue = (ahead.normalized || ahead.value).toLowerCase();
+        if (aheadValue === leadingMarker) {
+          this.logger.debug(
+            "  >> MARKER SCAN: found",
+            leadingMarker,
+            "at offset",
+            offset,
+            "- skipping intervening tokens"
+          );
+          for (let s = 0; s < offset; s++) tokens.advance();
+          const retrySuccess = this.matchTokenSequence(tokens, patternToken.tokens, captured);
+          if (retrySuccess) return true;
+          tokens.reset(mark);
+          for (const role of captured.keys()) {
+            if (!capturedBefore.has(role)) captured.delete(role);
+          }
+          break;
+        }
+      }
+    }
+    return true;
+  }
+  /**
+   * Get the leading marker literal from an optional group.
+   * Returns the lowercase marker value, or null if the group
+   * doesn't start with a literal token (e.g., SOV groups where
+   * the role comes before the marker).
+   */
+  getGroupLeadingMarker(group) {
+    const first = group.tokens[0];
+    if (first?.type === "literal") return first.value.toLowerCase();
+    return null;
+  }
+  /**
+   * Get the type of match for a token against a value.
+   * Used for confidence calculation.
+   */
+  getMatchType(token, value) {
+    if (token.value === value) return "exact";
+    if (token.normalized === value) return "normalized";
+    if (token.stem === value && token.stemConfidence !== void 0 && token.stemConfidence >= 0.7) {
+      return "stem";
+    }
+    if (token.kind === "keyword" && this.safeToLowerCase(token.value) === value.toLowerCase()) {
+      return "case-insensitive";
+    }
+    return "none";
+  }
+  /**
+   * Collect literal values from upcoming pattern tokens that act as stop markers
+   * for greedy role capture. Returns the set of lowercase values.
+   */
+  collectStopMarkers(patternTokens, startIndex) {
+    const markers = /* @__PURE__ */ new Set();
+    for (let j = startIndex; j < patternTokens.length; j++) {
+      const pt = patternTokens[j];
+      if (pt.type === "literal") {
+        markers.add(pt.value.toLowerCase());
+        if (pt.alternatives) {
+          for (const alt of pt.alternatives) {
+            markers.add(alt.toLowerCase());
+          }
+        }
+        break;
+      }
+      if (pt.type === "group") {
+        for (const gt of pt.tokens) {
+          if (gt.type === "literal") {
+            markers.add(gt.value.toLowerCase());
+            if (gt.alternatives) {
+              for (const alt of gt.alternatives) {
+                markers.add(alt.toLowerCase());
+              }
+            }
+            break;
+          }
+        }
+        break;
+      }
+    }
+    return markers;
+  }
+  /**
+   * Check if a token matches any stop marker for greedy capture.
+   */
+  isStopMarker(token, stopMarkers) {
+    if (stopMarkers.size === 0) return false;
+    const value = (token.normalized || token.value).toLowerCase();
+    return stopMarkers.has(value);
+  }
+  /**
+   * Convert a language token to a semantic value.
+   */
+  tokenToSemanticValue(token) {
+    switch (token.kind) {
+      case "selector":
+        return createSelector(token.value);
+      case "literal":
+        return this.parseLiteralValue(token.value);
+      case "keyword":
+        const tokenValue = token.normalized || token.value;
+        const lower = this.safeToLowerCase(tokenValue);
+        if (isValidReference(lower)) {
+          return createReference(lower);
+        }
+        return createLiteral(token.normalized || token.value);
+      case "identifier":
+        if (typeof token.value === "string" && token.value.startsWith(":")) {
+          return createReference(token.value);
+        }
+        const identLower = this.safeToLowerCase(token.value);
+        if (isValidReference(identLower)) {
+          return createReference(identLower);
+        }
+        return { type: "expression", raw: token.value };
+      case "url":
+        return createLiteral(token.value, "string");
+      default:
+        return null;
+    }
+  }
+  /**
+   * Parse a literal value (string, number, boolean).
+   */
+  parseLiteralValue(value) {
+    if (value.startsWith('"') || value.startsWith("'") || value.startsWith("`") || value.startsWith("\u300C")) {
+      const inner = value.slice(1, -1);
+      return createLiteral(inner, "string");
+    }
+    if (value === "true") return createLiteral(true, "boolean");
+    if (value === "false") return createLiteral(false, "boolean");
+    const durationMatch = value.match(/^(\d+(?:\.\d+)?)(ms|s|m|h)?$/);
+    if (durationMatch) {
+      const num2 = parseFloat(durationMatch[1]);
+      const unit = durationMatch[2];
+      if (unit) {
+        return createLiteral(value, "duration");
+      }
+      return createLiteral(num2, "number");
+    }
+    const num = parseFloat(value);
+    if (!isNaN(num)) {
+      return createLiteral(num, "number");
+    }
+    return createLiteral(value, "string");
+  }
+  /**
+   * Apply extraction rules to fill in static values and defaults for missing roles.
+   */
+  applyExtractionRules(pattern, captured) {
+    for (const [role, rule] of Object.entries(pattern.extraction)) {
+      if (!captured.has(role)) {
+        if (rule.value !== void 0) {
+          captured.set(role, { type: "literal", value: rule.value });
+        } else if (rule.default) {
+          captured.set(role, rule.default);
+        }
+      }
+    }
+  }
+  /**
+   * Check if a pattern token is optional.
+   */
+  isOptional(patternToken) {
+    return patternToken.type !== "literal" && patternToken.optional === true;
+  }
+  /**
+   * Calculate confidence score for a match (0-1).
+   *
+   * Confidence is reduced for:
+   * - Stem matches (morphological normalization has inherent uncertainty)
+   * - Missing optional roles (but less penalty if role has a default value)
+   *
+   * Confidence is increased for:
+   * - VSO languages (Arabic) when pattern starts with a verb
+   */
+  calculateConfidence(pattern, captured) {
+    let score = 0;
+    let maxScore = 0;
+    const hasDefault = (role) => {
+      return pattern.extraction?.[role]?.default !== void 0;
+    };
+    for (const token of pattern.template.tokens) {
+      if (token.type === "role") {
+        maxScore += 1;
+        if (captured.has(token.role)) {
+          score += 1;
+        }
+      } else if (token.type === "group") {
+        for (const subToken of token.tokens) {
+          if (subToken.type === "role") {
+            const roleHasDefault = hasDefault(subToken.role);
+            const weight = 0.8;
+            maxScore += weight;
+            if (captured.has(subToken.role)) {
+              score += weight;
+            } else if (roleHasDefault) {
+              score += weight * 0.6;
+            }
+          }
+        }
+      }
+    }
+    let baseConfidence = maxScore > 0 ? score / maxScore : 1;
+    if (this.stemMatchCount > 0 && this.totalKeywordMatches > 0) {
+      const stemPenalty = this.stemMatchCount / this.totalKeywordMatches * 0.15;
+      baseConfidence = Math.max(0.5, baseConfidence - stemPenalty);
+    }
+    const vsoBoost = this.calculateVSOConfidenceBoost(pattern);
+    baseConfidence = Math.min(1, baseConfidence + vsoBoost);
+    const prepositionAdjustment = this.arabicPrepositionDisambiguation(pattern, captured);
+    baseConfidence = Math.max(0, Math.min(1, baseConfidence + prepositionAdjustment));
+    return baseConfidence;
+  }
+  /**
+   * Calculate confidence boost for VSO (Verb-Subject-Object) language patterns.
+   * Arabic naturally uses VSO word order, so patterns that start with a verb
+   * should receive a confidence boost.
+   *
+   * Returns +0.15 confidence boost if:
+   * - Language is Arabic ('ar')
+   * - Pattern's first token is a verb keyword
+   *
+   * @param pattern The language pattern being matched
+   * @returns Confidence boost (0 or 0.15)
+   */
+  calculateVSOConfidenceBoost(pattern) {
+    if (pattern.language !== "ar") {
+      return 0;
+    }
+    const firstToken = pattern.template.tokens[0];
+    if (!firstToken || firstToken.type !== "literal") {
+      return 0;
+    }
+    const ARABIC_VERBS = /* @__PURE__ */ new Set([
+      "\u0628\u062F\u0644",
+      "\u063A\u064A\u0631",
+      "\u0623\u0636\u0641",
+      "\u0623\u0632\u0644",
+      "\u0636\u0639",
+      "\u0627\u062C\u0639\u0644",
+      "\u0639\u064A\u0646",
+      "\u0632\u062F",
+      "\u0627\u0646\u0642\u0635",
+      "\u0633\u062C\u0644",
+      "\u0623\u0638\u0647\u0631",
+      "\u0623\u062E\u0641",
+      "\u0634\u063A\u0644",
+      "\u0623\u0631\u0633\u0644",
+      "\u0631\u0643\u0632",
+      "\u0634\u0648\u0634",
+      "\u062A\u0648\u0642\u0641",
+      "\u0627\u0646\u0633\u062E",
+      "\u0627\u062D\u0630\u0641",
+      "\u0627\u0635\u0646\u0639",
+      "\u0627\u0646\u062A\u0638\u0631",
+      "\u0627\u0646\u062A\u0642\u0627\u0644",
+      "\u0623\u0648"
+    ]);
+    if (ARABIC_VERBS.has(firstToken.value)) {
+      return 0.15;
+    }
+    if (firstToken.alternatives) {
+      for (const alt of firstToken.alternatives) {
+        if (ARABIC_VERBS.has(alt)) {
+          return 0.15;
+        }
+      }
+    }
+    return 0;
+  }
+  /**
+   * Arabic preposition disambiguation for confidence adjustment.
+   *
+   * Different Arabic prepositions are more or less natural for different semantic roles:
+   * - على (on/upon) is preferred for patient/target roles (element selectors)
+   * - إلى (to) is preferred for destination roles
+   * - من (from) is preferred for source roles
+   * - في (in) is preferred for location roles
+   *
+   * This method analyzes the prepositions used with captured semantic roles and
+   * adjusts confidence based on idiomaticity:
+   * - +0.10 for highly idiomatic preposition choices
+   * - -0.10 for less natural preposition choices
+   *
+   * @param pattern The language pattern being matched
+   * @param captured The captured semantic values
+   * @returns Confidence adjustment (-0.10 to +0.10)
+   */
+  arabicPrepositionDisambiguation(pattern, captured) {
+    if (pattern.language !== "ar") {
+      return 0;
+    }
+    let adjustment = 0;
+    const PREFERRED_PREPOSITIONS = {
+      patient: ["\u0639\u0644\u0649"],
+      // element selectors prefer على (on/upon)
+      destination: ["\u0625\u0644\u0649", "\u0627\u0644\u0649"],
+      // destination prefers إلى (to)
+      source: ["\u0645\u0646"],
+      // source prefers من (from)
+      agent: ["\u0645\u0646"],
+      // agent/by prefers من (from/by)
+      manner: ["\u0628"],
+      // manner prefers ب (with/by)
+      style: ["\u0628"],
+      // style prefers ب (with)
+      goal: ["\u0625\u0644\u0649", "\u0627\u0644\u0649"],
+      // target state prefers إلى (to)
+      method: ["\u0628"]
+      // method prefers ب (with/by)
+    };
+    for (const [role, value] of captured.entries()) {
+      const preferred = PREFERRED_PREPOSITIONS[role];
+      if (!preferred || preferred.length === 0) {
+        continue;
+      }
+      const metadata = "metadata" in value ? value.metadata : void 0;
+      if (metadata && typeof metadata.prepositionValue === "string") {
+        const usedPreposition = metadata.prepositionValue;
+        if (preferred.includes(usedPreposition)) {
+          adjustment += 0.1;
+        } else {
+          adjustment -= 0.1;
+        }
+      }
+    }
+    return Math.max(-0.1, Math.min(0.1, adjustment));
+  }
+  /**
+   * Skip noise words like "the" before selectors.
+   * This enables more natural English syntax like "toggle the .active".
+   */
+  skipNoiseWords(tokens) {
+    const token = tokens.peek();
+    if (!token) return;
+    const tokenLower = this.safeToLowerCase(token.value);
+    if (_PatternMatcher.ENGLISH_NOISE_WORDS.has(tokenLower)) {
+      const mark = tokens.mark();
+      tokens.advance();
+      const nextToken = tokens.peek();
+      if (nextToken && nextToken.kind === "selector") {
+        return;
+      }
+      tokens.reset(mark);
+    }
+    if (tokenLower === "class") {
+      tokens.advance();
+    }
+  }
+  /**
+   * Extract event modifiers from the token stream.
+   * Event modifiers are .once, .debounce(N), .throttle(N), .queue(strategy)
+   * that can appear after event names.
+   *
+   * Returns EventModifiers object or undefined if no modifiers found.
+   */
+  extractEventModifiers(tokens) {
+    const modifiers = {};
+    let foundModifier = false;
+    while (!tokens.isAtEnd()) {
+      const token = tokens.peek();
+      if (!token || token.kind !== "event-modifier") {
+        break;
+      }
+      const metadata = token.metadata;
+      if (!metadata) {
+        break;
+      }
+      foundModifier = true;
+      switch (metadata.modifierName) {
+        case "once":
+          modifiers.once = true;
+          break;
+        case "debounce":
+          if (typeof metadata.value === "number") {
+            modifiers.debounce = metadata.value;
+          }
+          break;
+        case "throttle":
+          if (typeof metadata.value === "number") {
+            modifiers.throttle = metadata.value;
+          }
+          break;
+        case "queue":
+          if (metadata.value === "first" || metadata.value === "last" || metadata.value === "all" || metadata.value === "none") {
+            modifiers.queue = metadata.value;
+          }
+          break;
+      }
+      tokens.advance();
+    }
+    return foundModifier ? modifiers : void 0;
+  }
+};
+/** Maximum tokens to scan ahead when looking for a group's leading marker */
+_PatternMatcher.MAX_MARKER_SCAN = 3;
+// ==========================================================================
+// Depth Limits for Expression Parsing (security hardening)
+// ==========================================================================
+/** Maximum depth for nested property access (e.g., a.b.c.d...) */
+_PatternMatcher.MAX_PROPERTY_DEPTH = 10;
+/** Maximum number of arguments in method calls */
+_PatternMatcher.MAX_METHOD_ARGS = 20;
+// ===========================================================================
+// English Idiom Support - Noise Word Handling
+// ===========================================================================
+/**
+ * Noise words that can be skipped in English for more natural syntax.
+ * - "the" before selectors: "toggle the .active" → "toggle .active"
+ * - "class" after class selectors: "add the .visible class" → "add .visible"
+ */
+_PatternMatcher.ENGLISH_NOISE_WORDS = /* @__PURE__ */ new Set(["the", "a", "an"]);
+var PatternMatcher = _PatternMatcher;
+var patternMatcher = new PatternMatcher();
+function matchPattern(tokens, pattern) {
+  return patternMatcher.matchPattern(tokens, pattern);
+}
+function matchBest(tokens, patterns) {
+  return patternMatcher.matchBest(tokens, patterns);
+}
+export {
+  PatternMatcher,
+  getAllPossessiveKeywords,
+  getPossessiveReference,
+  isBuiltInReference,
+  isCSSPropertyRef,
+  isCSSSelector,
+  isClassName,
+  isIdSelector,
+  isNumericValue,
+  isPossessiveKeyword,
+  isPropertyName,
+  isTypeCompatible,
+  isVariableRef,
+  matchBest,
+  matchPattern,
+  patternMatcher,
+  validateValueType
+};
+//# sourceMappingURL=index.js.map