dirac-browser 0.1.1

package/examples/llm-reflection-test.di

@@ -0,0 +1,18 @@
+<dirac>
+  <subroutine name="inventory" description="Shows the current inventory.">
+    <eval>
+      emit(session, 'Inventory: apples=5, oranges=3');
+    </eval>
+  </subroutine>
+
+  <subroutine name="order" description="Places an order for an item." param-item="string:required:Item name" param-quantity="number:required:Quantity">
+    <parameters select="@item"/>
+    <parameters select="@quantity"/>
+    <eval>
+      emit(session, `Order placed: ${item} x ${quantity}`);
+    </eval>
+  </subroutine>
+
+  <llm>Show me my inventory</llm>
+  <llm>Order 2 apples</llm>
+</dirac>

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "dirac-browser",
+  "version": "0.1.1",
+  "description": "Browser-compatible Dirac language interpreter (no Node.js dependencies)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch"
+  },
+  "keywords": ["dirac", "interpreter", "browser", "frontend"],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "typescript": "^5.3.3"
+  },
+  "dependencies": {
+    "fast-xml-parser": "^4.3.4"
+  }
+}

package/src/chatbox.ts

@@ -0,0 +1,89 @@
+/**
+ * Dirac Chatbox Web Component
+ * Usage: <dirac-chatbox resource="/assets/ui-services.dirac.xml"></dirac-chatbox>
+ */
+import { execute, createSession } from './index.js';
+
+class DiracChatbox extends HTMLElement {
+  private resourceUrl: string = '';
+  private session: any;
+  private shadow: ShadowRoot;
+  private resourceLoaded: boolean = false;
+
+  constructor() {
+    super();
+    this.shadow = this.attachShadow({ mode: 'open' });
+    this.render();
+  }
+
+  static get observedAttributes() {
+    return ['resource'];
+  }
+
+  attributeChangedCallback(name: string, oldValue: string, newValue: string) {
+    if (name === 'resource' && newValue) {
+      this.resourceUrl = newValue;
+      this.loadResource();
+    }
+  }
+
+  connectedCallback() {
+    if (this.getAttribute('resource')) {
+      this.resourceUrl = this.getAttribute('resource')!;
+      this.loadResource();
+    }
+  }
+
+  async loadResource() {
+    try {
+      const res = await fetch(this.resourceUrl);
+      const xml = await res.text();
+      this.session = createSession({});
+      await execute(xml, this.session.config); // Register subroutines
+      this.resourceLoaded = true;
+    } catch (err) {
+      this.shadow.innerHTML = `<div style="color:red">Failed to load resource: ${err}</div>`;
+    }
+  }
+
+  render() {
+    this.shadow.innerHTML = `
+      <style>
+        .chatbox { border: 1px solid #ccc; padding: 1em; border-radius: 8px; width: 100%; max-width: 400px; font-family: sans-serif; }
+        .messages { min-height: 100px; margin-bottom: 1em; }
+        .input-row { display: flex; gap: 0.5em; }
+        input[type=text] { flex: 1; padding: 0.5em; border-radius: 4px; border: 1px solid #aaa; }
+        button { padding: 0.5em 1em; border-radius: 4px; border: none; background: #007bff; color: white; cursor: pointer; }
+        button:disabled { background: #aaa; }
+      </style>
+      <div class="chatbox">
+        <div class="messages"></div>
+        <form class="input-row">
+          <input type="text" placeholder="Type your message..." />
+          <button type="submit">Send</button>
+        </form>
+      </div>
+    `;
+    this.shadow.querySelector('form')!.addEventListener('submit', e => this.onSend(e));
+  }
+
+  async onSend(e: Event) {
+    e.preventDefault();
+    const input = this.shadow.querySelector('input[type=text]') as HTMLInputElement;
+    const messages = this.shadow.querySelector('.messages')!;
+    const userMsg = input.value.trim();
+    if (!userMsg || !this.resourceLoaded) return;
+    messages.innerHTML += `<div><b>You:</b> ${userMsg}</div>`;
+    input.value = '';
+    // Execute Dirac with <llm>userMsg</llm>
+    const script = `<llm>${userMsg}</llm>`;
+    try {
+      const result = await execute(script, this.session.config);
+      messages.innerHTML += `<div><b>Dirac:</b> ${result}</div>`;
+    } catch (err) {
+      messages.innerHTML += `<div style="color:red"><b>Error:</b> ${err}</div>`;
+    }
+  }
+}
+
+customElements.define('dirac-chatbox', DiracChatbox);

package/src/index.ts

@@ -0,0 +1,47 @@
+/**
+ * Dirac Language Browser Edition
+ * Browser-compatible interpreter without Node.js dependencies
+ */
+
+export { DiracParser } from './runtime/parser.js';
+export { createSession, getOutput, getAvailableSubroutines } from './runtime/session.js';
+export { integrate } from './runtime/interpreter.js';
+export { createLLMAdapter, executeUserCommand } from './utils/llm-adapter.js';
+export type { DiracSession, DiracConfig, DiracElement, ParameterMetadata } from './types/index.js';
+export type { LLMPromptGenerator } from './utils/llm-adapter.js';
+
+import { DiracParser } from './runtime/parser.js';
+import { createSession, getOutput } from './runtime/session.js';
+import { integrate } from './runtime/interpreter.js';
+import type { DiracConfig } from './types/index.js';
+
+/**
+ * Execute Dirac source code in browser
+ * 
+ * @param source - Dirac XML/HTML source code
+ * @param config - Configuration including customContext for injecting services
+ * @returns Promise resolving to output string
+ * 
+ * @example
+ * ```typescript
+ * const script = `
+ *   <sequence>
+ *     <defvar name="x"><eval>42</eval></defvar>
+ *     <output><variable name="x"/></output>
+ *   </sequence>
+ * `;
+ * 
+ * const result = await execute(script, {
+ *   customContext: { myService: serviceInstance }
+ * });
+ * ```
+ */
+export async function execute(source: string, config: DiracConfig = {}): Promise<string> {
+  const parser = new DiracParser();
+  const session = createSession(config);
+  
+  const ast = parser.parse(source);
+  await integrate(session, ast);
+  
+  return getOutput(session);
+}

package/src/runtime/braket-parser.ts

@@ -0,0 +1,234 @@
+/**
+ * Bra-Ket Parser - Converts bra-ket notation to XML
+ * 
+ * Syntax:
+ * - Bra (subroutine): <name| ... defines a subroutine
+ * - Ket (everything else): |tag attrs> ... can have children/content
+ * - Indentation: Defines scope (like Python/YAML)
+ * 
+ * Examples:
+ *   |output>Hello World          →  <output>Hello World</output>
+ *   |variable name=x>            →  <variable name="x"/>
+ *   <add|                        →  <subroutine name="add">
+ *     |output>test               →    <output>test</output>
+ *                                →  </subroutine>
+ */
+
+interface BraKetLine {
+  indent: number;
+  type: 'bra' | 'ket' | 'text' | 'empty';
+  tag?: string;
+  attrs?: string;
+  text?: string;
+  raw: string;
+}
+
+export class BraKetParser {
+  private lines: string[] = [];
+  private currentLine = 0;
+
+  /**
+   * Parse bra-ket notation and compile to XML
+   */
+  parse(source: string): string {
+    this.lines = source.split('\n');
+    this.currentLine = 0;
+
+    const xml: string[] = ['<dirac>'];
+    this.parseBlock(xml, -1);
+    xml.push('</dirac>');
+
+    return xml.join('\n');
+  }
+
+  /**
+   * Parse a block of lines at a given indentation level
+   */
+  private parseBlock(output: string[], parentIndent: number): void {
+    while (this.currentLine < this.lines.length) {
+      const line = this.parseLine(this.lines[this.currentLine]);
+
+      // Empty lines are preserved as-is
+      if (line.type === 'empty') {
+        this.currentLine++;
+        continue;
+      }
+
+      // If indent is less than or equal to parent, we're done with this block
+      if (line.indent <= parentIndent) {
+        break;
+      }
+
+      // Bra: <name| defines a subroutine
+      if (line.type === 'bra') {
+        const attrs = line.attrs ? ` ${this.convertAttributes(line.attrs)}` : '';
+        output.push(`${'  '.repeat(line.indent)}<subroutine name="${line.tag}"${attrs}>`);
+        this.currentLine++;
+        this.parseBlock(output, line.indent);
+        output.push(`${'  '.repeat(line.indent)}</subroutine>`);
+        continue;
+      }
+
+      // Ket: |tag attrs>
+      if (line.type === 'ket') {
+        const indent = '  '.repeat(line.indent);
+        const attrs = line.attrs ? ` ${this.convertAttributes(line.attrs)}` : '';
+        
+        // Check if next line is more indented (has children/content)
+        const nextLine = this.currentLine + 1 < this.lines.length 
+          ? this.parseLine(this.lines[this.currentLine + 1])
+          : null;
+
+        if (nextLine && nextLine.indent > line.indent && nextLine.type !== 'empty') {
+          // Has children - opening tag
+          output.push(`${indent}<${line.tag}${attrs}>`);
+          this.currentLine++;
+          this.parseBlock(output, line.indent);
+          output.push(`${indent}</${line.tag}>`);
+        } else {
+          // Self-closing or inline text
+          if (line.text) {
+            // Inline text with embedded kets
+            const content = this.convertInlineKets(line.text);
+            output.push(`${indent}<${line.tag}${attrs}>${content}</${line.tag}>`);
+          } else {
+            // Self-closing
+            output.push(`${indent}<${line.tag}${attrs}/>`);
+          }
+          this.currentLine++;
+        }
+        continue;
+      }
+
+      // Plain text content
+      if (line.type === 'text') {
+        const indent = '  '.repeat(line.indent);
+        const content = this.convertInlineKets(line.text || '');
+        output.push(`${indent}${content}`);
+        this.currentLine++;
+        continue;
+      }
+    }
+  }
+
+  /**
+   * Parse a single line into structured form
+   */
+  private parseLine(raw: string): BraKetLine {
+    // Count leading spaces for indentation
+    const match = raw.match(/^(\s*)(.*)/);
+    const indent = match ? Math.floor(match[1].length / 2) : 0;
+    const content = match ? match[2] : '';
+
+    // Empty line
+    if (!content.trim()) {
+      return { indent, type: 'empty', raw };
+    }
+
+    // Bra: <name| or <name attrs|
+    const braMatch = content.match(/^<([a-zA-Z_][a-zA-Z0-9_-]*)\s*([^|]*)\|$/);
+    if (braMatch) {
+      return {
+        indent,
+        type: 'bra',
+        tag: braMatch[1],
+        attrs: braMatch[2].trim() || undefined,
+        raw
+      };
+    }
+
+    // Ket: |tag> or |tag attrs> or |tag>text
+    const ketMatch = content.match(/^\|([a-zA-Z_][a-zA-Z0-9_-]*)\s*([^>]*?)>\s*(.*)/);
+    if (ketMatch) {
+      return {
+        indent,
+        type: 'ket',
+        tag: ketMatch[1],
+        attrs: ketMatch[2].trim() || undefined,
+        text: ketMatch[3] || undefined,
+        raw
+      };
+    }
+
+    // Plain text
+    return {
+      indent,
+      type: 'text',
+      text: content,
+      raw
+    };
+  }
+
+  /**
+   * Convert bra-ket attribute syntax to XML
+   * Examples:
+   *   name=value    → name="value"
+   *   x=5 y=10      → x="5" y="10"
+   *   select=@*     → select="@*"
+   */
+  private convertAttributes(attrs: string): string {
+    if (!attrs) return '';
+
+    // Split by spaces but respect quoted strings
+    const parts: string[] = [];
+    let current = '';
+    let inQuotes = false;
+    let quoteChar = '';
+
+    for (let i = 0; i < attrs.length; i++) {
+      const char = attrs[i];
+      
+      if ((char === '"' || char === "'") && (i === 0 || attrs[i - 1] !== '\\')) {
+        if (!inQuotes) {
+          inQuotes = true;
+          quoteChar = char;
+          current += char;
+        } else if (char === quoteChar) {
+          inQuotes = false;
+          current += char;
+        } else {
+          current += char;
+        }
+      } else if (char === ' ' && !inQuotes) {
+        if (current.trim()) {
+          parts.push(current.trim());
+          current = '';
+        }
+      } else {
+        current += char;
+      }
+    }
+    
+    if (current.trim()) {
+      parts.push(current.trim());
+    }
+
+    // Convert each attribute
+    return parts.map(part => {
+      const match = part.match(/^([a-zA-Z_][a-zA-Z0-9_-]*)=(.+)$/);
+      if (!match) return part;
+
+      const [, name, value] = match;
+      
+      // Already quoted
+      if ((value.startsWith('"') && value.endsWith('"')) ||
+          (value.startsWith("'") && value.endsWith("'"))) {
+        return `${name}=${value}`;
+      }
+
+      // Quote it
+      return `${name}="${value}"`;
+    }).join(' ');
+  }
+
+  /**
+   * Convert inline kets within text content
+   * Example: "Hello |variable name=x> world" → "Hello <variable name="x"/> world"
+   */
+  private convertInlineKets(text: string): string {
+    return text.replace(/\|([a-zA-Z_][a-zA-Z0-9_-]*)\s*([^>]*?)>/g, (match, tag, attrs) => {
+      const attrStr = attrs.trim() ? ` ${this.convertAttributes(attrs.trim())}` : '';
+      return `<${tag}${attrStr}/>`;
+    });
+  }
+}

package/src/runtime/interpreter.ts

@@ -0,0 +1,129 @@
+/**
+ * Core interpreter - Browser edition (no Node.js dependencies)
+ */
+
+import type { DiracElement, DiracSession } from '../types/index.js';
+import { substituteVariables, emit, getSubroutine } from './session.js';
+import { executeDefvar } from '../tags/defvar.js';
+import { executeVariable } from '../tags/variable.js';
+import { executeAssign } from '../tags/assign.js';
+import { executeOutput } from '../tags/output.js';
+import { executeSubroutine } from '../tags/subroutine.js';
+import { executeCall } from '../tags/call.js';
+import { executeLoop } from '../tags/loop.js';
+import { executeIf } from '../tags/if.js';
+import { executeEval } from '../tags/eval.js';
+import { executeExecute } from '../tags/execute.js';
+import { executeParameters } from '../tags/parameters.js';
+import { executeExpr } from '../tags/expr.js';
+import { executeLLM } from '../tags/llm.js';
+
+export async function integrate(session: DiracSession, element: DiracElement): Promise<void> {
+  // Check execution limits
+  if (session.limits.currentDepth >= session.limits.maxDepth) {
+    throw new Error('Maximum execution depth exceeded');
+  }
+  
+  session.limits.currentDepth++;
+  
+  try {
+    // Handle text nodes
+    if (element.text && !element.tag) {
+      const substituted = substituteVariables(session, element.text);
+      emit(session, substituted);
+      return;
+    }
+    
+    // Check control flow
+    if (session.isReturn || session.isBreak) {
+      return;
+    }
+    
+    // Dispatch to tag handlers
+    switch (element.tag.toLowerCase()) {
+      case 'defvar':
+        executeDefvar(session, element);
+        break;
+        
+      case 'variable':
+        executeVariable(session, element);
+        break;
+        
+      case 'assign':
+        executeAssign(session, element);
+        break;
+        
+      case 'output':
+        await executeOutput(session, element);
+        break;
+        
+      case 'subroutine':
+        executeSubroutine(session, element);
+        break;
+        
+      case 'call':
+        await executeCall(session, element);
+        break;
+        
+      case 'loop':
+        await executeLoop(session, element);
+        break;
+        
+      case 'if':
+        await executeIf(session, element);
+        break;
+        
+      case 'eval':
+        await executeEval(session, element);
+        break;
+        
+      case 'execute':
+        await executeExecute(session, element);
+        break;
+        
+      case 'parameters':
+        await executeParameters(session, element);
+        break;
+        
+      case 'expr':
+        await executeExpr(session, element);
+        break;
+      
+      // Browser-incompatible tags
+      case 'import':
+        console.warn('[dirac-browser] <import> tag not supported in browser (requires fs)');
+        break;
+        
+      case 'system':
+        console.warn('[dirac-browser] <system> tag not supported in browser (requires child_process)');
+        break;
+        
+      case 'llm':
+        await executeLLM(session, element);
+        break;
+        
+      default:
+        // Unknown tag - check if it's a subroutine name
+        const subroutine = getSubroutine(session, element.tag);
+        if (subroutine) {
+          // Treat unknown tag as subroutine call
+          await executeCall(session, element);
+        } else {
+          // Really unknown - just process children
+          for (const child of element.children) {
+            await integrate(session, child);
+            if (session.isReturn || session.isBreak) break;
+          }
+        }
+    }
+  } finally {
+    session.limits.currentDepth--;
+  }
+}
+
+export async function integrateChildren(session: DiracSession, element: DiracElement): Promise<void> {
+  for (const child of element.children) {
+    await integrate(session, child);
+    if (session.isReturn || session.isBreak) break;
+  }
+}

package/src/runtime/parser.ts

@@ -0,0 +1,151 @@
+/**
+ * XML Parser for Dirac (.di files)
+ */
+
+import { XMLParser } from 'fast-xml-parser';
+import type { DiracElement } from '../types/index.js';
+
+export class DiracParser {
+  private parser: XMLParser;
+  
+  constructor() {
+    this.parser = new XMLParser({
+      ignoreAttributes: false,
+      attributeNamePrefix: '@_',
+      trimValues: true,
+      parseAttributeValue: false,
+      parseTagValue: false,
+      textNodeName: '#text',
+      cdataPropName: '#cdata',
+      preserveOrder: true,  // Preserve element order!
+      commentPropName: '#comment',
+    });
+  }
+  
+  parse(source: string): DiracElement {
+    // Strip shebang line if present
+    if (source.startsWith('#!')) {
+      source = source.replace(/^#!.*\n/, '');
+    }
+    
+    const result = this.parser.parse(source);
+    // With preserveOrder, result is an array
+    if (!Array.isArray(result) || result.length === 0) {
+      throw new Error('Empty or invalid XML');
+    }
+    
+    // Find the first non-comment element
+    for (const item of result) {
+      if (!item['#comment']) {
+        return this.convertOrderedToElement(item);
+      }
+    }
+    
+    throw new Error('No root element found');
+  }
+  
+  private convertOrderedToElement(obj: any): DiracElement {
+    // obj is like { "tagname": [...children], ":@": {...attributes} }
+    const tagName = Object.keys(obj).find(k => k !== ':@' && k !== '#comment');
+    
+    if (!tagName) {
+      throw new Error('Invalid element structure');
+    }
+    
+    const element: DiracElement = {
+      tag: tagName,
+      attributes: {},
+      children: [],
+    };
+    
+    // Extract attributes
+    if (obj[':@']) {
+      for (const [key, value] of Object.entries(obj[':@'])) {
+        if (key.startsWith('@_')) {
+          element.attributes[key.slice(2)] = value as string;
+        }
+      }
+    }
+    
+    // Extract children
+    const children = obj[tagName];
+    if (Array.isArray(children)) {
+      for (const child of children) {
+        if (child['#text']) {
+          // Text node - add as child AND to element.text for backward compat
+          element.children.push({
+            tag: '',
+            text: child['#text'],
+            attributes: {},
+            children: []
+          });
+          // Also set element.text if not set (for simple text-only elements)
+          if (!element.text) {
+            element.text = child['#text'];
+          } else {
+            element.text += child['#text'];
+          }
+        } else if (child['#comment']) {
+          // Skip comments
+          continue;
+        } else {
+          // Child element
+          element.children.push(this.convertOrderedToElement(child));
+        }
+      }
+    }
+    
+    return element;
+  }
+  
+  // Old method - no longer used
+  private convertToElement(obj: any, tagName?: string): DiracElement {
+    if (!tagName) {
+      // Root level - find the actual tag
+      const keys = Object.keys(obj);
+      if (keys.length === 0) {
+        throw new Error('Empty XML');
+      }
+      tagName = keys[0];
+      obj = obj[tagName];
+    }
+    
+    const element: DiracElement = {
+      tag: tagName,
+      attributes: {},
+      children: [],
+    };
+    
+    if (typeof obj === 'string') {
+      element.text = obj;
+      return element;
+    }
+    
+    if (!obj) {
+      return element;
+    }
+    
+    // Extract attributes and children
+    for (const key of Object.keys(obj)) {
+      const value = obj[key];
+      
+      if (key === '#text') {
+        element.text = value;
+      } else if (key.startsWith('@_')) {
+        // Attribute
+        element.attributes[key.slice(2)] = value;
+      } else {
+        // Child element
+        if (Array.isArray(value)) {
+          for (const item of value) {
+            element.children.push(this.convertToElement(item, key));
+          }
+        } else {
+          element.children.push(this.convertToElement(value, key));
+        }
+      }
+    }
+    
+    return element;
+  }
+}