@lokascript/semantic 1.3.0 → 2.0.0

package/dist/interchange/from-semantic.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Semantic AST → Interchange Format Converter
+ *
+ * Converts the semantic package's AST builder output (types like 'eventHandler',
+ * 'binaryExpression', 'possessiveExpression') into the shared interchange format
+ * (types like 'event', 'binary', 'possessive').
+ *
+ * Also handles event modifier normalization — the semantic parser may store
+ * modifiers in a nested `eventModifiers` object, which is flattened here.
+ *
+ * This replaces the 586-line semantic-adapter.ts in the AOT compiler.
+ */
+import type { InterchangeNode } from './types';
+export type { InterchangeNode, EventModifiers } from './types';
+interface SemanticASTNode {
+    type: string;
+    [key: string]: unknown;
+}
+/**
+ * Convert a semantic AST builder node to an interchange node.
+ */
+export declare function fromSemanticAST(node: SemanticASTNode): InterchangeNode;
+//# sourceMappingURL=from-semantic.d.ts.map

package/dist/interchange/from-semantic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"from-semantic.d.ts","sourceRoot":"","sources":["../../src/interchange/from-semantic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EACV,eAAe,EAQhB,MAAM,SAAS,CAAC;AAGjB,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG/D,UAAU,eAAe;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAeD;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,eAAe,GAAG,eAAe,CAiHtE"}

package/dist/interchange/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Semantic → Interchange AST Converter
+ */
+export { fromSemanticAST } from './from-semantic';
+export type { InterchangeNode, EventModifiers } from './types';
+export type { EventNode, CommandNode, LiteralNode, IdentifierNode, SelectorNode, VariableNode, BinaryNode, UnaryNode, MemberNode, PossessiveNode, CallNode, IfNode, RepeatNode, ForEachNode, WhileNode, PositionalNode, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/interchange/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/interchange/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG/D,YAAY,EACV,SAAS,EACT,WAAW,EACX,WAAW,EACX,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,SAAS,EACT,UAAU,EACV,cAAc,EACd,QAAQ,EACR,MAAM,EACN,UAAU,EACV,WAAW,EACX,SAAS,EACT,cAAc,GACf,MAAM,SAAS,CAAC"}

package/dist/interchange/types.d.ts

@@ -0,0 +1,132 @@
+/**
+ * AST Interchange Format Types (Semantic-local copy)
+ *
+ * These are structurally identical to the canonical types in
+ * @hyperfixi/core/ast-utils/interchange/types.ts
+ *
+ * Duplicated here because the semantic package has no dependency on core.
+ * TypeScript's structural typing ensures these are assignable to the
+ * core package's versions when both are used by a consumer (e.g. AOT compiler).
+ */
+export type InterchangeNode = EventNode | CommandNode | LiteralNode | IdentifierNode | SelectorNode | VariableNode | BinaryNode | UnaryNode | MemberNode | PossessiveNode | CallNode | IfNode | RepeatNode | ForEachNode | WhileNode | PositionalNode;
+/**
+ * Position fields are optional — present when the source parser provides them,
+ * absent for synthetically constructed nodes.
+ */
+export interface BaseNode {
+    readonly type: string;
+    /** Byte offset of node start in source (0-indexed). */
+    readonly start?: number;
+    /** Byte offset of node end in source (0-indexed, exclusive). */
+    readonly end?: number;
+    /** Source line number (1-indexed). */
+    readonly line?: number;
+    /** Column offset within line (0-indexed). */
+    readonly column?: number;
+}
+export interface LiteralNode extends BaseNode {
+    readonly type: 'literal';
+    readonly value: string | number | boolean | null;
+}
+export interface IdentifierNode extends BaseNode {
+    readonly type: 'identifier';
+    readonly value: string;
+    readonly name?: string;
+}
+export interface SelectorNode extends BaseNode {
+    readonly type: 'selector';
+    readonly value: string;
+}
+export interface VariableNode extends BaseNode {
+    readonly type: 'variable';
+    readonly name: string;
+    readonly scope: 'local' | 'global' | 'element';
+}
+export interface BinaryNode extends BaseNode {
+    readonly type: 'binary';
+    readonly operator: string;
+    readonly left: InterchangeNode;
+    readonly right: InterchangeNode;
+}
+export interface UnaryNode extends BaseNode {
+    readonly type: 'unary';
+    readonly operator: string;
+    readonly operand: InterchangeNode;
+}
+export interface MemberNode extends BaseNode {
+    readonly type: 'member';
+    readonly object: InterchangeNode;
+    readonly property: string | InterchangeNode;
+    readonly computed?: boolean;
+}
+export interface PossessiveNode extends BaseNode {
+    readonly type: 'possessive';
+    readonly object: InterchangeNode;
+    readonly property: string;
+}
+export interface CallNode extends BaseNode {
+    readonly type: 'call';
+    readonly callee: InterchangeNode;
+    readonly args?: InterchangeNode[];
+}
+export interface PositionalNode extends BaseNode {
+    readonly type: 'positional';
+    readonly position: 'first' | 'last' | 'next' | 'previous' | 'closest' | 'parent' | 'random';
+    readonly target?: InterchangeNode;
+}
+export interface CommandNode extends BaseNode {
+    readonly type: 'command';
+    readonly name: string;
+    readonly args?: InterchangeNode[];
+    readonly target?: InterchangeNode;
+    readonly modifiers?: Record<string, unknown>;
+    /** Semantic roles from the semantic parser (patient, destination, source, etc.). */
+    readonly roles?: Readonly<Record<string, InterchangeNode>>;
+}
+export interface EventNode extends BaseNode {
+    readonly type: 'event';
+    readonly event: string;
+    readonly modifiers?: EventModifiers;
+    readonly body?: InterchangeNode[];
+    readonly target?: InterchangeNode;
+}
+export interface IfNode extends BaseNode {
+    readonly type: 'if';
+    readonly condition: InterchangeNode;
+    readonly thenBranch: InterchangeNode[];
+    readonly elseBranch?: InterchangeNode[];
+    readonly elseIfBranches?: ReadonlyArray<{
+        readonly condition: InterchangeNode;
+        readonly body: InterchangeNode[];
+    }>;
+}
+export interface RepeatNode extends BaseNode {
+    readonly type: 'repeat';
+    readonly count?: number | InterchangeNode;
+    readonly whileCondition?: InterchangeNode;
+    readonly untilEvent?: string;
+    readonly body: InterchangeNode[];
+}
+export interface ForEachNode extends BaseNode {
+    readonly type: 'foreach';
+    readonly itemName: string;
+    readonly indexName?: string;
+    readonly collection: InterchangeNode;
+    readonly body: InterchangeNode[];
+}
+export interface WhileNode extends BaseNode {
+    readonly type: 'while';
+    readonly condition: InterchangeNode;
+    readonly body: InterchangeNode[];
+}
+export interface EventModifiers {
+    readonly prevent?: boolean;
+    readonly stop?: boolean;
+    readonly once?: boolean;
+    readonly passive?: boolean;
+    readonly capture?: boolean;
+    readonly debounce?: number;
+    readonly throttle?: number;
+    readonly from?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/interchange/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/interchange/types.ts"],"names":[],"mappings":"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"}

package/dist/language-building-schema.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Language Building Schema
+ *
+ * This file defines the schema for adding languages and commands to the semantic parser.
+ * It serves as both documentation and validation for ensuring all required pieces are in place.
+ *
+ * ## Adding a New Language
+ *
+ * Required steps:
+ * 1. Create language profile in generators/language-profiles.ts
+ * 2. Create tokenizer in tokenizers/{language}.ts
+ * 3. Register tokenizer in tokenizers/index.ts
+ * 4. Create morphological normalizer in tokenizers/morphology/{language}-normalizer.ts (for agglutinative/inflected languages)
+ * 5. Add event handler patterns in patterns/event-handler.ts (if different from generated)
+ * 6. Add tests in test/official-examples.test.ts
+ * 7. Add morphology tests in test/morphology.test.ts (if normalizer created)
+ *
+ * ## Adding a New Command
+ *
+ * Required steps:
+ * 1. Define command schema in generators/command-schemas.ts
+ * 2. Wire schema in patterns/index.ts (generatePatternsForCommand)
+ * 3. Add keywords to ALL language profiles in generators/language-profiles.ts
+ * 4. Add keywords to ALL tokenizers' keyword maps
+ * 5. Add tests for all languages in test/official-examples.test.ts
+ *
+ * ## Morphological Infrastructure
+ *
+ * Languages with verb conjugations or inflections need morphological normalizers:
+ * - Japanese: て-form, た-form, ます-form, ている, etc.
+ * - Korean: 다 ending, 요/니다 forms, 았/었 past tense
+ * - Spanish: Conjugations (-ar, -er, -ir), reflexive verbs (mostrarse)
+ * - Arabic: Prefix/suffix stripping (ال, ي, ت, ن, أ, ون, ين)
+ * - Turkish: Vowel harmony, tense suffixes (-iyor, -di, -miş)
+ *
+ * The normalizer extracts the stem and provides a confidence score.
+ * Pattern matching uses stemmed forms when exact/normalized matches fail.
+ *
+ * ## Common Pitfalls
+ *
+ * - Keywords in language profiles but NOT in tokenizer keyword maps
+ *   → Tokens classified as 'identifier' instead of 'keyword'
+ *   → Pattern matching fails
+ *
+ * - Particle conflicts (e.g., Japanese 'に' used for both events and destinations)
+ *   → Event handler patterns match command patterns
+ *   → Solution: Use distinct particles or adjust pattern priorities
+ *
+ * - Missing keyword alternatives
+ *   → Native speakers may use different words for same concept
+ *   → Include common alternatives in both profile and tokenizer
+ *
+ * - Missing morphological normalizer for agglutinative languages
+ *   → Conjugated verb forms won't be recognized
+ *   → Solution: Create normalizer and integrate with tokenizer
+ */
+export interface LanguageChecklist {
+    /** ISO 639-1 language code */
+    code: string;
+    /** Human-readable language name */
+    name: string;
+    /** Word order (SVO, SOV, VSO) */
+    wordOrder: 'SVO' | 'SOV' | 'VSO';
+    /** Writing direction */
+    direction: 'ltr' | 'rtl';
+    /** Required files */
+    files: {
+        /** Language profile exists in generators/language-profiles.ts */
+        languageProfile: boolean;
+        /** Tokenizer exists in tokenizers/{code}.ts */
+        tokenizer: boolean;
+        /** Tokenizer registered in tokenizers/index.ts */
+        tokenizerRegistered: boolean;
+        /** Morphological normalizer in tokenizers/morphology/{code}-normalizer.ts */
+        morphologicalNormalizer: boolean;
+        /** Event handler patterns in patterns/event-handler.ts (optional for generated) */
+        eventHandlerPatterns: boolean;
+        /** Tests in test/official-examples.test.ts */
+        tests: boolean;
+        /** Morphology tests in test/morphology.test.ts */
+        morphologyTests: boolean;
+    };
+    /** Morphological infrastructure details */
+    morphology: {
+        /** Whether this language needs morphological normalization */
+        needed: boolean;
+        /** Why it's needed (or not needed) */
+        reason: string;
+        /** Types of inflections handled */
+        inflectionTypes: string[];
+        /** Whether the normalizer is integrated with the tokenizer */
+        integratedWithTokenizer: boolean;
+        /** Confidence threshold for stemmed matches */
+        confidenceThreshold: number;
+    };
+    /** Keywords defined in language profile */
+    profileKeywords: string[];
+    /** Keywords defined in tokenizer keyword map */
+    tokenizerKeywords: string[];
+    /** Keywords missing from tokenizer (profile has, tokenizer doesn't) */
+    missingFromTokenizer: string[];
+    /** Particles/markers that may cause conflicts */
+    potentialConflicts: ParticleConflict[];
+}
+export interface ParticleConflict {
+    /** The particle/marker */
+    particle: string;
+    /** What it's used for (e.g., 'destination', 'event', 'object') */
+    usedFor: string[];
+    /** Whether this causes actual pattern conflicts */
+    isResolved: boolean;
+    /** How it was resolved */
+    resolution?: string;
+}
+export interface CommandChecklist {
+    /** Command action name */
+    action: string;
+    /** Whether schema exists in generators/command-schemas.ts */
+    schemaExists: boolean;
+    /** Whether wired in patterns/index.ts (false for hand-crafted patterns) */
+    wiredInPatterns: boolean;
+    /** Whether this command uses hand-crafted patterns instead of generated */
+    usesHandCraftedPatterns: boolean;
+    /** Languages with profile keywords defined */
+    profileKeywordsIn: string[];
+    /** Languages with tokenizer keywords defined */
+    tokenizerKeywordsIn: string[];
+    /** Languages missing tokenizer keywords */
+    missingTokenizerKeywordsIn: string[];
+    /** Tests exist for each language */
+    testsFor: string[];
+}
+/**
+ * Validates that a language has all required pieces in place.
+ */
+export declare function validateLanguage(checklist: LanguageChecklist): ValidationResult;
+/**
+ * Validates that a command has all required pieces in place.
+ */
+export declare function validateCommand(checklist: CommandChecklist): ValidationResult;
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Documents the current state of language support.
+ * Update this when adding new languages or commands.
+ */
+export declare const SUPPORTED_LANGUAGES: LanguageChecklist[];
+/**
+ * Documents the current state of command support.
+ */
+export declare const SUPPORTED_COMMANDS: CommandChecklist[];
+/**
+ * Step-by-step process for adding a new language.
+ */
+export declare const ADD_LANGUAGE_PROCESS = "\n# Adding a New Language\n\n## Step 1: Create Language Profile\nFile: packages/semantic/src/generators/language-profiles.ts\n\nAdd a new profile with:\n- code: ISO 639-1 code (e.g., 'de' for German)\n- name: Human-readable name\n- wordOrder: 'SVO', 'SOV', or 'VSO'\n- direction: 'ltr' or 'rtl'\n- keywords: Map of command \u2192 { primary, alternatives, normalized }\n- particles: Object marking case/role particles\n- prepositions: Destination/source markers\n\n## Step 2: Create Tokenizer\nFile: packages/semantic/src/tokenizers/{code}.ts\n\nCopy structure from similar language tokenizer:\n- Character classification functions (if non-Latin script)\n- KEYWORDS map: native words \u2192 English normalized\n- Particle detection\n- Word extraction logic\n\n## Step 3: Register Tokenizer\nFile: packages/semantic/src/tokenizers/index.ts\n\n- Import tokenizer\n- Add to tokenizers map\n- Add to exports\n\n## Step 4: Add Event Handler Patterns (if needed)\nFile: packages/semantic/src/patterns/event-handler.ts\n\nIf the language needs custom event handler syntax:\n- Add pattern for standard event form\n- Add pattern for source-filtered events\n- Add event name translations\n\n## Step 5: Add Tests\nFile: packages/semantic/test/official-examples.test.ts\n\nAdd tests for:\n- Basic commands (toggle, add, put)\n- Commands with targets\n- Multilingual equivalents section\n- AST equivalence tests\n\n## Step 6: Update Documentation\nFile: packages/semantic/src/language-building-schema.ts\n\nAdd entry to SUPPORTED_LANGUAGES array.\n";
+/**
+ * Step-by-step process for adding a new command.
+ */
+export declare const ADD_COMMAND_PROCESS = "\n# Adding a New Command\n\n## Step 1: Define Command Schema\nFile: packages/semantic/src/generators/command-schemas.ts\n\nAdd schema with:\n- action: command name\n- description: what it does\n- category: 'dom-class', 'dom-content', 'variable', etc.\n- primaryRole: main semantic role\n- roles: array of RoleSpec with:\n  - role: semantic role name\n  - description\n  - required: boolean\n  - expectedTypes: ['selector', 'literal', 'reference', 'expression']\n  - default: optional default value\n  - svoPosition/sovPosition: word order hints\n\n## Step 2: Add Keywords to Language Profiles\nFile: packages/semantic/src/generators/language-profiles.ts\n\nFor EACH language profile, add:\n```typescript\n{command}: {\n  primary: 'native_word',\n  alternatives: ['alt1', 'alt2'],\n  normalized: 'command',\n}\n```\n\n## Step 3: Add Keywords to Tokenizers\nFiles: packages/semantic/src/tokenizers/{language}.ts\n\nFor EACH tokenizer's KEYWORDS map, add:\n```typescript\n['native_word', 'command'],\n['alternative1', 'command'],\n['alternative2', 'command'],\n```\n\n## Step 4: Wire Schema in Pattern Registry\nFile: packages/semantic/src/patterns/index.ts\n\n- Import schema from generators\n- Add to generatedPatterns array:\n  `...generatePatternsForCommand({command}Schema),`\n\n## Step 5: Add Tests\nFile: packages/semantic/test/official-examples.test.ts\n\nAdd tests for:\n- English syntax\n- Each supported language\n- Edge cases (implicit targets, etc.)\n\n## Step 6: Update Documentation\nFile: packages/semantic/src/language-building-schema.ts\n\nAdd entry to SUPPORTED_COMMANDS array.\n";
+//# sourceMappingURL=language-building-schema.d.ts.map

package/dist/language-building-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"language-building-schema.d.ts","sourceRoot":"","sources":["../src/language-building-schema.ts"],"names":[],"mappings":"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"}

package/dist/language-loader.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Language Loader
+ *
+ * Provides lazy loading capabilities for language modules.
+ * Languages can be loaded:
+ * 1. Via dynamic import from package subpath
+ * 2. From a URL (for CDN usage)
+ * 3. From a pre-loaded module object
+ *
+ * @example
+ * ```typescript
+ * import { loadLanguage, parse } from '@lokascript/semantic/browser/lazy';
+ *
+ * // Load Japanese on demand
+ * await loadLanguage('ja');
+ *
+ * // Now parsing works for Japanese
+ * parse('トグル .active', 'ja');
+ * ```
+ */
+import { type LanguageProfile } from './registry';
+import type { LanguageTokenizer, LanguagePattern } from './types';
+/**
+ * Options for loading a language.
+ */
+export interface LoadLanguageOptions {
+    /**
+     * URL to fetch the language module from (for CDN usage).
+     * The module should export: tokenizer, profile, patterns (or buildPatterns)
+     */
+    url?: string;
+    /**
+     * Pre-loaded module object.
+     * Use this if you've already imported the module.
+     */
+    module?: LanguageModule;
+    /**
+     * Skip loading if the language is already registered.
+     * Defaults to true.
+     */
+    skipIfRegistered?: boolean;
+}
+/**
+ * A language module that can be registered with the semantic parser.
+ */
+export interface LanguageModule {
+    /** The language tokenizer */
+    tokenizer: LanguageTokenizer;
+    /** The language profile for pattern generation */
+    profile: LanguageProfile;
+    /** Pre-built patterns (optional) */
+    patterns?: LanguagePattern[];
+    /** Function to build patterns lazily (optional) */
+    buildPatterns?: () => LanguagePattern[];
+}
+/**
+ * Result of a language loading operation.
+ */
+export interface LoadLanguageResult {
+    /** The language code that was loaded */
+    code: string;
+    /** Whether the language was newly loaded (false if already registered) */
+    loaded: boolean;
+    /** Error message if loading failed */
+    error?: string;
+}
+/**
+ * List of all supported language codes.
+ */
+export declare const SUPPORTED_LANGUAGES: string[];
+/**
+ * Load a single language.
+ *
+ * @param code - The language code (e.g., 'en', 'ja', 'es')
+ * @param options - Loading options
+ * @returns Result indicating success or failure
+ *
+ * @example
+ * ```typescript
+ * // Load from package
+ * await loadLanguage('ja');
+ *
+ * // Load from CDN
+ * await loadLanguage('ko', {
+ *   url: 'https://cdn.example.com/hyperfixi-semantic-ko.js'
+ * });
+ *
+ * // Load from pre-loaded module
+ * await loadLanguage('en', { module: myEnglishModule });
+ * ```
+ */
+export declare function loadLanguage(code: string, options?: LoadLanguageOptions): Promise<LoadLanguageResult>;
+/**
+ * Load multiple languages in parallel.
+ *
+ * @param codes - Array of language codes to load
+ * @param options - Loading options (applied to all languages)
+ * @returns Array of results for each language
+ *
+ * @example
+ * ```typescript
+ * // Load multiple languages
+ * const results = await loadLanguages(['en', 'es', 'ja']);
+ *
+ * // Check results
+ * for (const result of results) {
+ *   if (result.error) {
+ *     console.error(`Failed to load ${result.code}: ${result.error}`);
+ *   }
+ * }
+ * ```
+ */
+export declare function loadLanguages(codes: string[], options?: Omit<LoadLanguageOptions, 'module'>): Promise<LoadLanguageResult[]>;
+/**
+ * Check if a language can be loaded (is supported).
+ */
+export declare function canLoadLanguage(code: string): boolean;
+/**
+ * Get list of languages that are currently loaded.
+ */
+export declare function getLoadedLanguages(): string[];
+/**
+ * Get list of languages that are not yet loaded.
+ */
+export declare function getUnloadedLanguages(): string[];
+//# sourceMappingURL=language-loader.d.ts.map

package/dist/language-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"language-loader.d.ts","sourceRoot":"","sources":["../src/language-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAMlE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;IAExB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,6BAA6B;IAC7B,SAAS,EAAE,iBAAiB,CAAC;IAE7B,kDAAkD;IAClD,OAAO,EAAE,eAAe,CAAC;IAEzB,oCAAoC;IACpC,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;IAE7B,mDAAmD;IACnD,aAAa,CAAC,EAAE,MAAM,eAAe,EAAE,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IAEb,0EAA0E;IAC1E,MAAM,EAAE,OAAO,CAAC;IAEhB,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAyID;;GAEG;AACH,eAAO,MAAM,mBAAmB,UAAkC,CAAC;AA2DnE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,kBAAkB,CAAC,CAqC7B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,GAAE,IAAI,CAAC,mBAAmB,EAAE,QAAQ,CAAM,GAChD,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAE/B;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAE7C;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,EAAE,CAE/C"}

package/dist/languages/_all.d.ts

@@ -0,0 +1,66 @@
+/**
+ * All Languages Module
+ *
+ * Imports and registers all 25 supported languages.
+ * Use this for the full bundle with all language support.
+ *
+ * @example
+ * ```typescript
+ * import '@lokascript/semantic/languages/_all';
+ * // or
+ * import '@lokascript/semantic/languages';
+ * ```
+ *
+ * @generated This file is auto-generated. Do not edit manually.
+ */
+import './ar';
+import './bn';
+import './de';
+import './en';
+import './es';
+import './es-MX';
+import './fr';
+import './he';
+import './hi';
+import './id';
+import './it';
+import './ja';
+import './ko';
+import './ms';
+import './pl';
+import './pt';
+import './qu';
+import './ru';
+import './sw';
+import './th';
+import './tl';
+import './tr';
+import './uk';
+import './vi';
+import './zh';
+export * from './ar';
+export * from './bn';
+export * from './de';
+export * from './en';
+export * from './es';
+export * from './es-MX';
+export * from './fr';
+export * from './he';
+export * from './hi';
+export * from './id';
+export * from './it';
+export * from './ja';
+export * from './ko';
+export * from './ms';
+export * from './pl';
+export * from './pt';
+export * from './qu';
+export * from './ru';
+export * from './sw';
+export * from './th';
+export * from './tl';
+export * from './tr';
+export * from './uk';
+export * from './vi';
+export * from './zh';
+//# sourceMappingURL=_all.d.ts.map

package/dist/languages/_all.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_all.d.ts","sourceRoot":"","sources":["../../src/languages/_all.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,MAAM,CAAC;AACd,OAAO,MAAM,CAAC;AACd,OAAO,MAAM,CAAC;AACd,OAAO,MAAM,CAAC;AACd,OAAO,MAAM,CAAC;AACd,OAAO,SAAS,CAAC;AACjB,OAAO,MAAM,CAAC;AACd,OAAO,MAAM,CAAC;AACd,OAAO,MAAM,CAAC;AACd,OAAO,MAAM,CAAC;AACd,OAAO,MAAM,CAAC;AACd,OAAO,MAAM,CAAC;AACd,OAAO,MAAM,CAAC;AACd,OAAO,MAAM,CAAC;AACd,OAAO,MAAM,CAAC;AACd,OAAO,MAAM,CAAC;AACd,OAAO,MAAM,CAAC;AACd,OAAO,MAAM,CAAC;AACd,OAAO,MAAM,CAAC;AACd,OAAO,MAAM,CAAC;AACd,OAAO,MAAM,CAAC;AACd,OAAO,MAAM,CAAC;AACd,OAAO,MAAM,CAAC;AACd,OAAO,MAAM,CAAC;AACd,OAAO,MAAM,CAAC;AAGd,cAAc,MAAM,CAAC;AACrB,cAAc,MAAM,CAAC;AACrB,cAAc,MAAM,CAAC;AACrB,cAAc,MAAM,CAAC;AACrB,cAAc,MAAM,CAAC;AACrB,cAAc,SAAS,CAAC;AACxB,cAAc,MAAM,CAAC;AACrB,cAAc,MAAM,CAAC;AACrB,cAAc,MAAM,CAAC;AACrB,cAAc,MAAM,CAAC;AACrB,cAAc,MAAM,CAAC;AACrB,cAAc,MAAM,CAAC;AACrB,cAAc,MAAM,CAAC;AACrB,cAAc,MAAM,CAAC;AACrB,cAAc,MAAM,CAAC;AACrB,cAAc,MAAM,CAAC;AACrB,cAAc,MAAM,CAAC;AACrB,cAAc,MAAM,CAAC;AACrB,cAAc,MAAM,CAAC;AACrB,cAAc,MAAM,CAAC;AACrB,cAAc,MAAM,CAAC;AACrB,cAAc,MAAM,CAAC;AACrB,cAAc,MAAM,CAAC;AACrB,cAAc,MAAM,CAAC;AACrB,cAAc,MAAM,CAAC"}

package/dist/languages/ar.d.ts

@@ -1,78 +1,9 @@
-import { B as BaseTokenizer, T as TokenStream, a as TokenKind, L as LanguageProfile } from '../types-BY3Id07j.js';
-
 /**
- * Arabic Tokenizer
+ * Arabic Language Module
  *
- * Tokenizes Arabic hyperscript input.
- * Arabic is challenging because:
- * - Right-to-left (RTL) text direction
- * - Prefix prepositions that attach to words (بـ, لـ, كـ)
- * - Root-pattern morphology
- * - CSS selectors are LTR islands within RTL text
+ * Self-registering module for Arabic language support.
+ * Importing this module registers Arabic tokenizer and profile.
  */
-
-declare class ArabicTokenizer extends BaseTokenizer {
-    readonly language = "ar";
-    readonly direction: "rtl";
-    constructor();
-    tokenize(input: string): TokenStream;
-    classifyToken(token: string): TokenKind;
-    /**
-     * Try to match an Arabic preposition.
-     * Attaches prepositionValue metadata for disambiguation in pattern matching.
-     */
-    private tryPreposition;
-    /**
-     * Try to extract a proclitic (conjunction or preposition) that's attached to the following word.
-     *
-     * Arabic proclitics attach directly to words without space:
-     * - والنقر → و + النقر (and + the-click)
-     * - فالتبديل → ف + التبديل (then + the-toggle)
-     * - بالنقر → ب + النقر (with + the-click)
-     * - ولالنقر → و + ل + النقر (and + to + the-click)
-     *
-     * This enables:
-     * - Polysyndetic coordination: A وB وC
-     * - Attached prepositions: بالنقر (with-the-click)
-     * - Multi-proclitic sequences: ولالنقر (and-to-the-click)
-     *
-     * Returns null if:
-     * - Not a proclitic character/sequence
-     * - Proclitic is standalone (followed by space)
-     * - Remaining word is too short (< 2 chars, to avoid false positives)
-     * - Full word is a recognized keyword (e.g., بدل should NOT be split to ب + دل)
-     *
-     * @see NATIVE_REVIEW_NEEDED.md for implementation rationale
-     */
-    private tryProclitic;
-    /**
-     * Extract an Arabic word.
-     * Uses morphological normalization to handle prefix/suffix variations.
-     * Attaches metadata for temporal markers (formality, confidence).
-     */
-    private extractArabicWord;
-    /**
-     * Extract an ASCII word.
-     */
-    private extractAsciiWord;
-    /**
-     * Extract a number, including Arabic time unit suffixes.
-     * Arabic allows space between number and unit.
-     */
-    private extractArabicNumber;
-}
-/**
- * Singleton instance.
- */
-declare const arabicTokenizer: ArabicTokenizer;
-
-/**
- * Arabic Language Profile
- *
- * VSO word order, prepositions, RTL (right-to-left), space-separated.
- * Features root-based morphology and rich verb conjugation.
- */
-
-declare const arabicProfile: LanguageProfile;
-
-export { arabicProfile, arabicTokenizer };
+export { arabicTokenizer } from '../tokenizers/arabic';
+export { arabicProfile } from '../generators/profiles/arabic';
+//# sourceMappingURL=ar.d.ts.map

package/dist/languages/ar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ar.d.ts","sourceRoot":"","sources":["../../src/languages/ar.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC"}