@lokascript/hyperscript-adapter 2.0.0

package/src/bundles/tr.ts

@@ -0,0 +1,6 @@
+/** Self-contained: Turkish (renders to English via custom renderer) */
+import '@lokascript/semantic/languages/tr';
+export { plugin, preprocess, resolveLanguage } from './shared';
+export const supportedLanguages = ['tr'];
+import { autoRegister } from './shared';
+autoRegister();

package/src/bundles/uk.ts

@@ -0,0 +1,6 @@
+/** Self-contained: Ukrainian (renders to English via custom renderer) */
+import '@lokascript/semantic/languages/uk';
+export { plugin, preprocess, resolveLanguage } from './shared';
+export const supportedLanguages = ['uk'];
+import { autoRegister } from './shared';
+autoRegister();

package/src/bundles/vi.ts

@@ -0,0 +1,6 @@
+/** Self-contained: Vietnamese (renders to English via custom renderer) */
+import '@lokascript/semantic/languages/vi';
+export { plugin, preprocess, resolveLanguage } from './shared';
+export const supportedLanguages = ['vi'];
+import { autoRegister } from './shared';
+autoRegister();

package/src/bundles/western.ts

@@ -0,0 +1,9 @@
+/** Self-contained: Western/European languages (es, pt, fr, de) */
+import '@lokascript/semantic/languages/es';
+import '@lokascript/semantic/languages/pt';
+import '@lokascript/semantic/languages/fr';
+import '@lokascript/semantic/languages/de';
+export { plugin, preprocess, resolveLanguage } from './shared';
+export const supportedLanguages = ['es', 'pt', 'fr', 'de'];
+import { autoRegister } from './shared';
+autoRegister();

package/src/bundles/zh.ts

@@ -0,0 +1,6 @@
+/** Self-contained: Chinese (renders to English via custom renderer) */
+import '@lokascript/semantic/languages/zh';
+export { plugin, preprocess, resolveLanguage } from './shared';
+export const supportedLanguages = ['zh'];
+import { autoRegister } from './shared';
+autoRegister();

package/src/derive-syntax.ts

@@ -0,0 +1,126 @@
+/**
+ * Derive SYNTAX tables from CommandSchema definitions.
+ *
+ * Instead of maintaining a hand-coded SYNTAX table that can drift from
+ * the canonical schemas, this module generates it from the semantic
+ * package's command-schemas + language profile.
+ *
+ * The generated table maps each command to ordered [role, preposition]
+ * tuples for rendering.
+ */
+
+import type { CommandSchema, RoleSpec, LanguageProfile } from '@lokascript/semantic';
+import type { RoleMarker } from '@lokascript/semantic/core';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type SyntaxEntry = readonly [string, string][];
+export type SyntaxTable = Record<string, SyntaxEntry>;
+
+// ---------------------------------------------------------------------------
+// Overrides for commands whose rendering doesn't cleanly derive from
+// schema roles (different role names, simplified structure, etc.)
+// ---------------------------------------------------------------------------
+
+/**
+ * Commands where the SYNTAX rendering uses a different mapping
+ * than what derives from schema roles + language profile.
+ *
+ * - repeat: Schema has loopType/quantity/event/source, but English renders
+ *           as "repeat N" or "repeat until <condition>" using simplified roles
+ */
+const RENDER_OVERRIDES: SyntaxTable = {
+  repeat: [
+    ['quantity', ''],
+    ['condition', 'until'],
+  ],
+};
+
+// ---------------------------------------------------------------------------
+// Derivation
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the preposition for a role in a specific command and language.
+ *
+ * Priority:
+ * 1. Render-specific override for this language (renderOverride[lang])
+ * 2. Command-specific marker override for this language (markerOverride[lang])
+ * 3. Language profile's default roleMarker for this role
+ * 4. '' (no preposition)
+ */
+function resolvePreposition(roleSpec: RoleSpec, profile: LanguageProfile, lang: string): string {
+  // 1. Render-time override for this language
+  if (roleSpec.renderOverride?.[lang] !== undefined) {
+    return roleSpec.renderOverride[lang];
+  }
+
+  // 2. Command-specific marker override for this language
+  if (roleSpec.markerOverride?.[lang] !== undefined) {
+    return roleSpec.markerOverride[lang];
+  }
+
+  // 3. Profile default for this role
+  const roleMarker = (profile.roleMarkers as Record<string, RoleMarker | undefined>)[roleSpec.role];
+  if (roleMarker) {
+    return roleMarker.primary;
+  }
+
+  // 4. No preposition
+  return '';
+}
+
+/**
+ * Derive the SYNTAX table from command schemas and a language profile.
+ *
+ * For each command:
+ * - Sort roles by position (svoPosition for SVO/VSO, sovPosition for SOV)
+ * - Resolve each role's preposition for the given language
+ * - Return [role, preposition] tuples
+ *
+ * Commands in RENDER_OVERRIDES use their manual entry instead (English only).
+ */
+export function deriveSyntax(
+  schemas: Record<string, CommandSchema>,
+  profile: LanguageProfile,
+  lang: string
+): SyntaxTable {
+  const syntax: Record<string, [string, string][]> = {};
+  const isSov = profile.wordOrder === 'SOV';
+
+  for (const [action, schema] of Object.entries(schemas)) {
+    // Use manual override for commands that don't derive cleanly (English only)
+    if (lang === 'en' && RENDER_OVERRIDES[action]) {
+      syntax[action] = RENDER_OVERRIDES[action] as [string, string][];
+      continue;
+    }
+
+    // Sort roles by position appropriate for word order
+    const sortedRoles = [...schema.roles].sort((a, b) => {
+      const posA = isSov ? (a.sovPosition ?? 99) : (a.svoPosition ?? 99);
+      const posB = isSov ? (b.sovPosition ?? 99) : (b.svoPosition ?? 99);
+      return posA - posB;
+    });
+
+    // Derive [role, preposition] tuples
+    syntax[action] = sortedRoles.map(roleSpec => [
+      roleSpec.role,
+      resolvePreposition(roleSpec, profile, lang),
+    ]);
+  }
+
+  return syntax;
+}
+
+/**
+ * Derive the English SYNTAX table.
+ * Convenience wrapper that calls deriveSyntax with 'en'.
+ */
+export function deriveEnglishSyntax(
+  schemas: Record<string, CommandSchema>,
+  englishProfile: LanguageProfile
+): SyntaxTable {
+  return deriveSyntax(schemas, englishProfile, 'en');
+}

package/src/generated/syntax-table.ts

@@ -0,0 +1,61 @@
+// @generated — do not edit manually.
+// Regenerate with: npm run generate:syntax
+//
+// Derived from command schemas + English profile via deriveEnglishSyntax().
+
+export const SYNTAX: Record<string, readonly [string, string][]> = {
+  add: [['patient', ''], ['destination', 'to']],
+  append: [['patient', ''], ['destination', 'to']],
+  async: [],
+  beep: [['patient', '']],
+  behavior: [['patient', '']],
+  blur: [['patient', '']],
+  break: [],
+  call: [['patient', '']],
+  clone: [['patient', ''], ['destination', 'into']],
+  compound: [],
+  continue: [],
+  copy: [['patient', '']],
+  decrement: [['patient', ''], ['quantity', 'by']],
+  default: [['destination', ''], ['patient', 'to']],
+  else: [],
+  exit: [],
+  fetch: [['source', ''], ['responseType', 'as'], ['method', 'via'], ['destination', 'on']],
+  focus: [['patient', '']],
+  for: [['patient', ''], ['source', 'in']],
+  get: [['source', ''], ['destination', 'on']],
+  go: [['destination', '']],
+  halt: [['patient', '']],
+  hide: [['patient', ''], ['style', 'with']],
+  if: [['condition', '']],
+  increment: [['patient', ''], ['quantity', 'by']],
+  init: [],
+  install: [['patient', ''], ['destination', 'on']],
+  js: [['patient', '']],
+  log: [['patient', '']],
+  make: [['patient', '']],
+  measure: [['patient', ''], ['source', 'of']],
+  morph: [['destination', ''], ['patient', 'to']],
+  on: [['event', ''], ['source', 'from']],
+  pick: [['patient', ''], ['source', 'from']],
+  prepend: [['patient', ''], ['destination', 'to']],
+  put: [['patient', ''], ['destination', 'into']],
+  remove: [['patient', ''], ['source', 'from']],
+  render: [['patient', ''], ['style', 'with']],
+  repeat: [['quantity', ''], ['condition', 'until']],
+  return: [['patient', '']],
+  send: [['event', ''], ['destination', 'to']],
+  set: [['destination', ''], ['patient', 'to']],
+  settle: [['patient', '']],
+  show: [['patient', ''], ['style', 'with']],
+  swap: [['method', ''], ['destination', 'of'], ['patient', 'with']],
+  take: [['patient', ''], ['source', 'from']],
+  tell: [['destination', '']],
+  throw: [['patient', '']],
+  toggle: [['patient', ''], ['destination', 'on']],
+  transition: [['patient', ''], ['goal', 'to'], ['destination', 'on'], ['duration', 'over'], ['style', 'with']],
+  trigger: [['event', ''], ['destination', 'on']],
+  unless: [['condition', '']],
+  wait: [['patient', '']],
+  while: [['condition', '']],
+};

package/src/hyperscript-renderer.ts

@@ -0,0 +1,150 @@
+/**
+ * Hyperscript English Renderer
+ *
+ * Purpose-built renderer that converts SemanticNodes to standard English
+ * _hyperscript syntax. Unlike the semantic package's renderer (which uses
+ * pattern matching and requires English patterns/tokenizer/profile),
+ * this is a deterministic mapping — no registry lookups needed.
+ *
+ * This eliminates ~35 KB of English language data from per-language bundles.
+ */
+
+import type {
+  SemanticNode,
+  SemanticValue,
+  SemanticRole,
+  EventHandlerSemanticNode,
+  CompoundSemanticNode,
+} from '@lokascript/semantic/core';
+
+// ---------------------------------------------------------------------------
+// Per-command syntax: ordered [role, preposition] tuples.
+// Empty string = no preposition (direct object).
+//
+// Generated from command schemas. Do not edit manually.
+// Regenerate with: npm run generate:syntax
+// ---------------------------------------------------------------------------
+
+import { SYNTAX } from './generated/syntax-table';
+export { SYNTAX };
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Render a SemanticNode to standard English _hyperscript syntax.
+ */
+export function renderToHyperscript(node: SemanticNode): string {
+  switch (node.kind) {
+    case 'event-handler':
+      return renderEventHandler(node as EventHandlerSemanticNode);
+    case 'compound':
+      return renderCompound(node as CompoundSemanticNode);
+    default:
+      return renderCommand(node);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Node-kind renderers
+// ---------------------------------------------------------------------------
+
+function renderEventHandler(node: EventHandlerSemanticNode): string {
+  const parts: string[] = ['on'];
+
+  // Event name
+  const event = node.roles.get('event');
+  if (event) {
+    parts.push(renderValue(event));
+  }
+
+  // Event source (from #element)
+  const source = node.roles.get('source');
+  if (source) {
+    parts.push('from', renderValue(source));
+  }
+
+  // Body commands
+  if (node.body && node.body.length > 0) {
+    const bodyParts = node.body.map(renderToHyperscript);
+    parts.push(bodyParts.join(' then '));
+  }
+
+  return parts.join(' ');
+}
+
+function renderCompound(node: CompoundSemanticNode): string {
+  const chainWord = node.chainType === 'async' ? 'async' : node.chainType;
+  return node.statements.map(renderToHyperscript).join(` ${chainWord} `);
+}
+
+function renderCommand(node: SemanticNode): string {
+  const syntax = SYNTAX[node.action];
+
+  // Known command: use syntax table
+  if (syntax) {
+    const parts: string[] = [node.action];
+    for (const [role, prep] of syntax) {
+      const value = node.roles.get(role as SemanticRole);
+      if (!value) continue;
+      // Skip implicit "me" destination (default in _hyperscript)
+      if (role === 'destination' && value.type === 'reference' && value.value === 'me') continue;
+      if (prep) parts.push(prep);
+      parts.push(renderValue(value));
+    }
+    return parts.join(' ');
+  }
+
+  // Unknown command: generic fallback — action then all roles
+  const parts: string[] = [node.action];
+  for (const [, value] of node.roles) {
+    parts.push(renderValue(value));
+  }
+  return parts.join(' ');
+}
+
+// ---------------------------------------------------------------------------
+// Value renderers
+// ---------------------------------------------------------------------------
+
+function renderValue(value: SemanticValue): string {
+  switch (value.type) {
+    case 'literal':
+      if (typeof value.value === 'string' && value.dataType === 'string') {
+        return `"${value.value}"`;
+      }
+      return String(value.value);
+
+    case 'selector':
+      return value.value;
+
+    case 'reference':
+      return value.value;
+
+    case 'property-path':
+      return renderPropertyPath(value);
+
+    case 'expression':
+      return value.raw;
+  }
+}
+
+function renderPropertyPath(value: SemanticValue & { type: 'property-path' }): string {
+  const objectStr = renderValue(value.object);
+  const property = value.property;
+
+  // English possessive special forms
+  if (value.object.type === 'reference') {
+    switch (value.object.value) {
+      case 'me':
+        return `my ${property}`;
+      case 'it':
+        return `its ${property}`;
+      case 'you':
+        return `your ${property}`;
+    }
+  }
+
+  return `${objectStr}'s ${property}`;
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+/**
+ * @lokascript/hyperscript-adapter
+ *
+ * Multilingual adapter plugin for the original _hyperscript.
+ * Enables writing hyperscript in any of 24 supported languages.
+ *
+ * @example
+ * import { hyperscriptI18n } from '@lokascript/hyperscript-adapter';
+ * _hyperscript.use(hyperscriptI18n());
+ *
+ * @example
+ * // With options
+ * _hyperscript.use(hyperscriptI18n({
+ *   defaultLanguage: 'ja',
+ *   debug: true,
+ * }));
+ *
+ * @example
+ * // Standalone preprocessing (for _hyperscript.evaluate() calls)
+ * import { preprocess } from '@lokascript/hyperscript-adapter';
+ * const english = preprocess('トグル .active', 'ja');
+ * _hyperscript(english);
+ */
+
+export { hyperscriptI18n, preprocess, type PluginOptions } from './plugin';
+export { preprocessToEnglish, type PreprocessorConfig } from './preprocessor';
+export { resolveLanguage } from './language-resolver';

package/src/language-resolver.ts

@@ -0,0 +1,41 @@
+/**
+ * Language Resolver
+ *
+ * Determines the language of hyperscript code on a given element
+ * using a cascading resolution strategy.
+ */
+
+/**
+ * Resolve the language for a hyperscript attribute on an element.
+ *
+ * Resolution order:
+ * 1. `data-lang` attribute on the element itself
+ * 2. `data-hyperscript-lang` attribute on the element or closest ancestor
+ * 3. `lang` attribute on `<html>` element
+ * 4. null (assume English, no preprocessing needed)
+ */
+export function resolveLanguage(elt: Element): string | null {
+  // 1. Explicit per-element
+  const dataLang = elt.getAttribute('data-lang');
+  if (dataLang) return normalizeLangCode(dataLang);
+
+  // 2. Inherited from ancestor
+  const hsLang =
+    elt.getAttribute('data-hyperscript-lang') ??
+    elt.closest?.('[data-hyperscript-lang]')?.getAttribute('data-hyperscript-lang');
+  if (hsLang) return normalizeLangCode(hsLang);
+
+  // 3. Document-level lang
+  const htmlLang = typeof document !== 'undefined' ? document.documentElement?.lang : null;
+  if (htmlLang && htmlLang !== 'en') return normalizeLangCode(htmlLang);
+
+  return null;
+}
+
+/**
+ * Normalize a BCP-47 language tag to an ISO 639-1 code.
+ * e.g., "ja-JP" → "ja", "zh-Hans" → "zh", "pt-BR" → "pt"
+ */
+function normalizeLangCode(lang: string): string {
+  return lang.split('-')[0].toLowerCase();
+}

package/src/plugin.ts

@@ -0,0 +1,119 @@
+/**
+ * _hyperscript Plugin
+ *
+ * Registers with _hyperscript.use() to intercept getScript() and
+ * preprocess non-English hyperscript into English before parsing.
+ */
+
+import { resolveLanguage } from './language-resolver';
+import { preprocessToEnglish, type PreprocessorConfig } from './preprocessor';
+
+/**
+ * The _hyperscript global object shape (minimal subset we need).
+ */
+interface HyperscriptGlobal {
+  internals: {
+    runtime: HyperscriptRuntime;
+  };
+  config: Record<string, unknown>;
+}
+
+interface HyperscriptRuntime {
+  getScript(elt: Element): string | null;
+}
+
+export interface PluginOptions extends Partial<PreprocessorConfig> {
+  /** Default language for all elements (overridable per-element). */
+  defaultLanguage?: string;
+  /** Custom attribute name for per-element language. Default: "data-lang" */
+  languageAttribute?: string;
+  /** Enable debug logging to console. Default: false */
+  debug?: boolean;
+}
+
+/**
+ * Create a _hyperscript plugin that enables multilingual hyperscript.
+ *
+ * @example
+ * // Basic usage
+ * _hyperscript.use(hyperscriptI18n());
+ *
+ * @example
+ * // With options
+ * _hyperscript.use(hyperscriptI18n({
+ *   defaultLanguage: 'ja',
+ *   confidenceThreshold: 0.6,
+ *   debug: true,
+ * }));
+ */
+export function hyperscriptI18n(options: PluginOptions = {}) {
+  return function plugin(hs: unknown): void {
+    const { internals } = hs as HyperscriptGlobal;
+    const runtime = internals.runtime;
+    const originalGetScript = runtime.getScript.bind(runtime);
+
+    runtime.getScript = function (elt: Element): string | null {
+      const src = originalGetScript(elt);
+      if (!src) return null;
+
+      // Resolve language
+      const lang = resolveLanguageWithOptions(elt, options);
+
+      // If English or no language detected, pass through
+      if (!lang || lang === 'en') return src;
+
+      // Preprocess to English
+      const english = preprocessToEnglish(src, lang, options);
+
+      if (english !== src) {
+        if (options.debug) {
+          console.log(`[hyperscript-i18n] ${lang}: "${src}" → "${english}"`);
+        }
+      } else {
+        // Translation produced no change — likely a failure
+        console.warn(
+          `[hyperscript-i18n] Translation unchanged for lang="${lang}": "${src.length > 60 ? src.slice(0, 60) + '…' : src}". ` +
+            'The input may not match any known pattern, or the language may not be registered. ' +
+            'Original text will be passed to _hyperscript as-is.'
+        );
+      }
+
+      return english;
+    };
+  };
+}
+
+/**
+ * Resolve language with plugin options factored in.
+ */
+function resolveLanguageWithOptions(elt: Element, options: PluginOptions): string | null {
+  // Check custom attribute name
+  if (options.languageAttribute) {
+    const custom = elt.getAttribute(options.languageAttribute);
+    if (custom) return custom.split('-')[0].toLowerCase();
+  }
+
+  // Standard resolution
+  const resolved = resolveLanguage(elt);
+  if (resolved) return resolved;
+
+  // Fall back to default language
+  return options.defaultLanguage ?? null;
+}
+
+/**
+ * Standalone preprocessing function for programmatic use.
+ * Call this when using _hyperscript.evaluate() or _hyperscript("code") directly.
+ *
+ * @example
+ * const english = preprocess("トグル .active", "ja");
+ * _hyperscript(english);
+ */
+export function preprocess(
+  src: string,
+  lang: string,
+  config: Partial<PreprocessorConfig> = {}
+): string {
+  if (lang === 'en') return src;
+  return preprocessToEnglish(src, lang, config);
+}