tjs-lang 0.5.4 → 0.5.5

package/demo/docs.json

@@ -681,6 +681,12 @@
     "filename": "from-ts.ts",
     "path": "src/lang/emitters/from-ts.ts"
   },
+  {
+    "title": "GEMINI.md - Project Context & Instructions",
+    "filename": "GEMINI.md",
+    "path": "GEMINI.md",
+    "text": "# GEMINI.md - Project Context & Instructions\n\nThis file provides foundational mandates and contextual information for Gemini CLI when working in the `tjs-lang` repository.\n\n## Project Overview\n\n**tjs-lang** is a platform for type-safe JavaScript execution and AI agent orchestration. It bridges the gap between static typing and runtime safety by preserving type information and providing a secure execution environment.\n\n### Core Languages\n\n1.  **TJS (Typed JavaScript):** A TypeScript-like dialect that transpiles to JavaScript with embedded `__tjs` metadata. This metadata enables runtime type validation, auto-documentation, and introspection.\n2.  **AJS (Agent JavaScript):** A safe, sandboxed language for AI agents. It compiles to a JSON-serializable AST and executes in a gas-limited VM with capability-based security.\n\n### Architecture\n\n- **Builder Layer** (`src/builder.ts`): Fluent API for constructing AST nodes.\n- **Runtime Layer** (`src/vm/runtime.ts`): Security-critical core that executes AST nodes and manages fuel/capabilities.\n- **Lang Layer** (`src/lang/`): Contains the parser (based on Acorn), linter, and emitters for TJS and AJS.\n- **Batteries** (`src/batteries/`): Built-in capabilities like LLM integration (LM Studio), vector search, and persistence.\n\n## Development Lifecycle\n\n### Common Commands\n\n- **Install:** `bun install`\n- **Build:** `npm run make` (Format, build grammars, compile TS, and bundle)\n- **Fast Test:** `npm run test:fast` (Runs core tests, skips LLM and benchmarks)\n- **Full Test:** `bun test`\n- **Type Check:** `npm run typecheck`\n- **Lint:** `npm run lint`\n- **Format:** `npm run format` (ESLint fix + Prettier)\n- **Dev Server:** `npm run dev`\n- **CLI Tool:** `bun src/cli/tjs.ts <command>` (Commands: `check`, `run`, `types`, `emit`, `convert`, `test`)\n\n### Testing Strategy\n\n- **Unit Tests:** Located alongside source files (e.g., `src/lang/parser.test.ts`).\n- **Integration Tests:** Located in `src/use-cases/`.\n- **Security Tests:** Critical for the VM, found in `src/use-cases/malicious-actor.test.ts`.\n- **Reproduction:** Always create a reproduction test case before fixing a bug.\n\n## Engineering Standards & Conventions\n\n### Coding Style\n\n- **Formatting:** Prettier (Single quotes, no semicolons, 2-space indentation, 80 char width).\n- **Naming:** Follow existing conventions; prefix unused variables with `_`.\n- **Type Safety:** Prioritize TypeScript for all core logic. `any` is allowed but should be used judiciously.\n- **Security:** Rigorously protect the `src/vm/runtime.ts` file as it is security-critical. Avoid prototype access (`__proto__`, `constructor`, `prototype`) in expression evaluation.\n\n### Language Specifics\n\n- **TJS Types:** In TJS, colons indicate _examples_, not just type annotations (e.g., `name: 'Alice'` means a required string).\n- **AJS Expressions:** Be aware that AJS expressions have differences from JS (e.g., safe null member access, limited computed member access).\n- **Monadic Errors:** Prefer returning error values (Monadic errors) over throwing exceptions to ensure execution stability and security.\n\n### Documentation\n\n- Maintain `DOCS-TJS.md` and `DOCS-AJS.md` for language-specific documentation.\n- Update `CLAUDE.md` for tool-specific guidance if architectural patterns change.\n\n## Contextual Precedence\n\n- **Directives:** Explicit requests for implementation take priority.\n- **Inquiries:** Requests for analysis or advice should not result in code changes without a subsequent Directive.\n- **Security First:** Never compromise the sandboxing or fuel-metering integrity of the VM.\n"
+  },
   {
     "title": "icebox",
     "filename": "tasks-f6d70f.md",

package/demo/src/demo-nav.ts

@@ -8,7 +8,7 @@
  * - TJS Docs (documentation that opens in floating viewer)
  */
 
-import { Component, elements, ElementCreator, vars, observe } from 'tosijs'
+import { Component, elements, ElementCreator, vars, bind } from 'tosijs'
 import {
   xinFloat,
   XinFloat,
@@ -75,6 +75,7 @@ interface DocItem {
 export class DemoNav extends Component {
   private _docs: DocItem[] = []
   private _appState: any = null // boxed proxy from index.ts
+  private _built = false
   private floatViewer: XinFloat | null = null
   private mdViewer: MarkdownViewer | null = null
 
@@ -93,42 +94,7 @@ export class DemoNav extends Component {
   set appState(state: any) {
     this._appState = state
     if (!state) return
-    // Observe state changes to update nav
-    observe(/^app\.(currentView|currentExample)/, () => {
-      this.rebuildNav()
-      this.updateCurrentIndicator()
-    })
-    observe('app.openSection', () => {
-      this.rebuildNav()
-    })
-    // Initial sync
-    this.rebuildNav()
-    this.updateCurrentIndicator()
-  }
-
-  private get _currentView(): string {
-    return this._appState?.currentView?.valueOf() ?? 'home'
-  }
-
-  private get _currentExampleName(): string | null {
-    const ex = this._appState?.currentExample?.valueOf()
-    if (!ex) return null
-    return ex.name || ex.title || null
-  }
-
-  private get _openSection(): string | null {
-    return this._appState?.openSection?.valueOf() ?? null
-  }
-
-  private updateCurrentIndicator() {
-    const exName = this._currentExampleName
-    const items = this.querySelectorAll('.nav-item')
-    items.forEach((item) => {
-      const itemName = item.textContent?.trim()
-      item.classList.toggle('current', itemName === exName)
-    })
-    const homeLink = this.querySelector('.home-link')
-    homeLink?.classList.toggle('current', this._currentView === 'home')
+    this.tryBuild()
   }
 
   get docs(): DocItem[] {
@@ -137,8 +103,16 @@ export class DemoNav extends Component {
 
   set docs(value: DocItem[]) {
     this._docs = value
-    this.rebuildNav()
-    this.updateCurrentIndicator()
+    this.tryBuild()
+  }
+
+  // Build nav once when both docs and appState are available
+  private tryBuild() {
+    if (this._built || !this._appState || !this._docs.length) return
+    const container = this.querySelector('.nav-sections')
+    if (!container) return
+    this._built = true
+    this.buildNav(container)
   }
 
   // Light DOM styles (no static styleSpec)
@@ -273,9 +247,7 @@ export class DemoNav extends Component {
 
   connectedCallback() {
     super.connectedCallback()
-    this.rebuildNav()
-    // Update indicator after DOM is ready
-    this.updateCurrentIndicator()
+    this.tryBuild()
   }
 
   // Group labels for display
@@ -316,199 +288,156 @@ export class DemoNav extends Component {
   >(examples: T[], renderItem: (ex: T) => HTMLElement): HTMLElement[] {
     const grouped = new Map<string, T[]>()
 
-    // Group examples
     for (const ex of examples) {
       const group = ex.group || 'other'
-      if (!grouped.has(group)) {
-        grouped.set(group, [])
-      }
+      if (!grouped.has(group)) grouped.set(group, [])
       grouped.get(group)!.push(ex)
     }
 
-    // Sort groups by GROUP_ORDER
     const sortedGroups = Array.from(grouped.keys()).sort((a, b) => {
       const orderA = DemoNav.GROUP_ORDER.indexOf(a)
       const orderB = DemoNav.GROUP_ORDER.indexOf(b)
       return (orderA === -1 ? 99 : orderA) - (orderB === -1 ? 99 : orderB)
     })
 
-    // Render groups with headers
-    const elements: HTMLElement[] = []
+    const elts: HTMLElement[] = []
     for (const group of sortedGroups) {
       const items = grouped.get(group)!
       const label = DemoNav.GROUP_LABELS[group] || group
-
-      // Add group header
-      elements.push(div({ class: 'group-header' }, label))
-
-      // Add items in this group
-      for (const ex of items) {
-        elements.push(renderItem(ex))
-      }
+      elts.push(div({ class: 'group-header' }, label))
+      for (const ex of items) elts.push(renderItem(ex))
     }
+    return elts
+  }
 
-    return elements
+  // Create a nav item bound to currentExample for highlighting
+  private boundNavItem(
+    name: string,
+    extra: { description?: string; requiresApi?: boolean },
+    onClick: () => void
+  ): HTMLElement {
+    const baseClass = extra.requiresApi ? 'nav-item requires-api' : 'nav-item'
+    const item = div(
+      {
+        class: baseClass,
+        title: extra.description,
+        'data-name': name,
+        onClick,
+      },
+      name
+    )
+    bind(item, 'app.currentExample', {
+      toDOM(el: HTMLElement, example: any) {
+        const current = example?.name || example?.title || null
+        el.classList.toggle('current', current === name)
+      },
+    })
+    return item
   }
 
-  rebuildNav() {
-    const container = this.querySelector('.nav-sections')
-    if (!container) return
+  // Create a details section bound to openSection for open/close
+  private boundSection(
+    sectionId: string,
+    icon: Element,
+    label: string,
+    children: HTMLElement[]
+  ): HTMLElement {
+    const det = details(
+      {
+        'data-section': sectionId,
+        onToggle: this.handleToggle,
+      },
+      summary(span({ class: 'section-icon' }, icon), label),
+      div({ class: 'section-content' }, ...children)
+    )
+    bind(det, 'app.openSection', {
+      toDOM(el: HTMLDetailsElement, section: string | null) {
+        el.open = section === sectionId
+      },
+    })
+    return det
+  }
 
-    container.innerHTML = ''
-    container.append(
-      // Home link
-      div(
-        {
-          class:
-            this._currentView === 'home' ? 'home-link current' : 'home-link',
-          onClick: () => this.selectHome(),
-        },
-        span({ class: 'section-icon' }, icons.home({ size: 16 })),
-        'Home'
-      ),
+  // Build the nav once — all reactive updates via bind
+  private buildNav(container: Element) {
+    const homeLink = div(
+      {
+        class: 'home-link',
+        onClick: () => this.selectHome(),
+      },
+      span({ class: 'section-icon' }, icons.home({ size: 16 })),
+      'Home'
+    )
+    bind(homeLink, 'app.currentView', {
+      toDOM(el: HTMLElement, view: string) {
+        el.classList.toggle('current', view === 'home')
+      },
+    })
 
-      // TypeScript Examples (TS -> TJS -> JS pipeline)
-      details(
-        {
-          open: this._openSection === 'ts-demos',
-          'data-section': 'ts-demos',
-          onToggle: this.handleToggle,
-        },
-        summary(
-          span({ class: 'section-icon' }, icons.code({ size: 16 })),
-          'TypeScript Examples'
-        ),
-        div(
-          { class: 'section-content' },
-          ...this.renderGroupedExamples(tsExamples, (ex) =>
-            div(
-              {
-                class: 'nav-item',
-                title: ex.description,
-                onClick: () => this.selectTsExample(ex),
-              },
-              ex.name
-            )
-          )
+    container.append(
+      homeLink,
+
+      this.boundSection(
+        'ts-demos',
+        icons.code({ size: 16 }),
+        'TypeScript Examples',
+        this.renderGroupedExamples(tsExamples, (ex) =>
+          this.boundNavItem(ex.name, ex, () => this.selectTsExample(ex))
         )
       ),
 
-      // TJS Examples
-      details(
-        {
-          open: this._openSection === 'tjs-demos',
-          'data-section': 'tjs-demos',
-          onToggle: this.handleToggle,
-        },
-        summary(
-          span({ class: 'section-icon' }, icons.code({ size: 16 })),
-          'TJS Examples'
-        ),
-        div(
-          { class: 'section-content' },
-          ...this.renderGroupedExamples(this.tjsExamples, (ex) =>
-            div(
-              {
-                class: 'nav-item',
-                title: ex.description,
-                onClick: () => this.selectTjsExample(ex),
-              },
-              ex.title || ex.name
-            )
-          )
-        )
+      this.boundSection(
+        'tjs-demos',
+        icons.code({ size: 16 }),
+        'TJS Examples',
+        this.renderGroupedExamples(this.tjsExamples, (ex) => {
+          const name = ex.title || ex.name || 'Untitled'
+          return this.boundNavItem(name, ex, () => this.selectTjsExample(ex))
+        })
       ),
 
-      // AJS Examples
-      details(
-        {
-          open: this._openSection === 'ajs-demos',
-          'data-section': 'ajs-demos',
-          onToggle: this.handleToggle,
-        },
-        summary(
-          span({ class: 'section-icon' }, icons.code({ size: 16 })),
-          'AJS Examples'
-        ),
-        div(
-          { class: 'section-content' },
-          ...this.renderGroupedExamples(this.ajsExamples, (ex) =>
-            div(
-              {
-                class: ex.requiresApi ? 'nav-item requires-api' : 'nav-item',
-                title: ex.description,
-                onClick: () => this.selectAjsExample(ex),
-              },
-              ex.title || ex.name
-            )
-          )
-        )
+      this.boundSection(
+        'ajs-demos',
+        icons.code({ size: 16 }),
+        'AJS Examples',
+        this.renderGroupedExamples(this.ajsExamples, (ex) => {
+          const name = ex.title || ex.name || 'Untitled'
+          return this.boundNavItem(name, ex, () => this.selectAjsExample(ex))
+        })
       ),
 
-      // TJS Docs
-      details(
-        {
-          open: this._openSection === 'tjs-docs',
-          'data-section': 'tjs-docs',
-          onToggle: this.handleToggle,
-        },
-        summary(
-          span({ class: 'section-icon' }, icons.book({ size: 16 })),
-          'TJS Docs'
-        ),
-        div(
-          { class: 'section-content' },
-          ...this.getTjsDocs().map((doc) =>
-            div(
-              {
-                class: 'nav-item',
-                onClick: () => this.selectDoc(doc),
-              },
-              doc.title
-            )
-          )
+      this.boundSection(
+        'tjs-docs',
+        icons.book({ size: 16 }),
+        'TJS Docs',
+        this.getTjsDocs().map((doc) =>
+          this.boundNavItem(doc.title, doc, () => this.selectDoc(doc))
         )
       ),
 
-      // AJS Docs
-      details(
-        {
-          open: this._openSection === 'ajs-docs',
-          'data-section': 'ajs-docs',
-          onToggle: this.handleToggle,
-        },
-        summary(
-          span({ class: 'section-icon' }, icons.book({ size: 16 })),
-          'AJS Docs'
-        ),
-        div(
-          { class: 'section-content' },
-          ...this.getAjsDocs().map((doc) =>
-            div(
-              {
-                class: 'nav-item',
-                onClick: () => this.selectDoc(doc),
-              },
-              doc.title
-            )
-          )
+      this.boundSection(
+        'ajs-docs',
+        icons.book({ size: 16 }),
+        'AJS Docs',
+        this.getAjsDocs().map((doc) =>
+          this.boundNavItem(doc.title, doc, () => this.selectDoc(doc))
         )
       )
     )
   }
 
   handleToggle = (event: Event) => {
-    const details = event.target as HTMLDetailsElement
-    const section = details.getAttribute('data-section')
-
-    if (details.open) {
-      if (this._appState) this._appState.openSection.value = section
-      // Close other sections (accordion behavior)
-      this.querySelectorAll('details').forEach((d) => {
-        if (d !== details && d.open) {
-          d.open = false
-        }
-      })
+    const det = event.target as HTMLDetailsElement
+    const section = det.getAttribute('data-section')
+    if (!this._appState) return
+
+    const current = this._appState.openSection.valueOf()
+    if (det.open && current !== section) {
+      // User opened a section — update state (bind handles the rest)
+      this._appState.openSection.value = section
+    } else if (!det.open && current === section) {
+      // User closed the current section
+      this._appState.openSection.value = null
     }
   }
 
@@ -602,6 +531,7 @@ export class DemoNav extends Component {
           padding: '4px',
           border: 'none',
           background: 'transparent',
+          color: vars.textColor,
           cursor: 'pointer',
         },
       },
@@ -620,7 +550,8 @@ export class DemoNav extends Component {
           width: '500px',
           maxWidth: 'calc(100vw - 40px)',
           maxHeight: '80vh',
-          background: 'white',
+          background: vars.background,
+          color: vars.textColor,
           borderRadius: '8px',
           boxShadow: '0 4px 20px rgba(0,0,0,0.15)',
           overflow: 'hidden',
@@ -634,13 +565,16 @@ export class DemoNav extends Component {
             display: 'flex',
             alignItems: 'center',
             padding: '6px 12px',
-            background: '#f3f4f6',
-            borderBottom: '1px solid #e5e7eb',
+            background: vars.codeBackground,
+            borderBottom: `1px solid ${vars.codeBorder}`,
             cursor: 'move',
           },
         },
         span(
-          { class: 'float-title', style: { flex: '1', fontWeight: '500' } },
+          {
+            class: 'float-title',
+            style: { flex: '1', fontWeight: '500', color: vars.textColor },
+          },
           doc.title
         ),
         closeBtn

package/demo/src/imports.ts

@@ -20,19 +20,28 @@ const moduleCache = new Map<string, string>()
 // Common packages with pinned versions and ESM paths
 // Packages with proper "exports" or "module" fields in package.json
 // may work without explicit paths, but it's safer to specify them
-const PINNED_PACKAGES: Record<
-  string,
-  { version: string; path?: string; cdn?: string }
-> = {
+interface PinnedPackage {
+  version: string
+  path?: string
+  cdn?: string
+  // Transitive deps to include in the import map when this package is imported
+  deps?: string[]
+}
+
+const PINNED_PACKAGES: Record<string, PinnedPackage> = {
   // tjs-lang itself (used by demos like Universal Endpoint)
   'tjs-lang': {
-    version: '0.5.1',
-    cdn: 'https://cdn.jsdelivr.net/npm/tjs-lang@0.5.1/dist/index.js',
+    version: '0.5.4',
+    cdn: 'https://cdn.jsdelivr.net/npm/tjs-lang@0.5.4/dist/index.js',
   },
 
   // tosijs ecosystem
   tosijs: { version: '1.2.0', path: '/dist/module.js' },
-  'tosijs-ui': { version: '1.2.0', path: '/dist/index.js' },
+  'tosijs-ui': {
+    version: '1.2.0',
+    path: '/dist/index.js',
+    deps: ['tosijs', 'marked'],
+  },
 
   // Utilities - lodash-es is native ESM
   'lodash-es': { version: '4.17.21' },
@@ -56,13 +65,38 @@ const PINNED_PACKAGES: Record<
   'react-dom': {
     version: '18.2.0',
     cdn: 'https://cdn.jsdelivr.net/npm/react-dom@18.2.0/+esm',
+    deps: ['react'],
   },
   'react-dom/client': {
     version: '18.2.0',
     cdn: 'https://cdn.jsdelivr.net/npm/react-dom@18.2.0/client/+esm',
+    deps: ['react', 'react-dom'],
   },
 }
 
+/**
+ * Expand a list of specifiers to include transitive deps from PINNED_PACKAGES.
+ * Walks the deps graph to collect all needed packages.
+ */
+function expandWithDeps(specifiers: string[]): string[] {
+  const all = new Set(specifiers)
+  const queue = [...specifiers]
+  while (queue.length > 0) {
+    const spec = queue.pop()!
+    const { name } = parseSpecifier(spec)
+    const pinned = PINNED_PACKAGES[spec] || PINNED_PACKAGES[name]
+    if (pinned?.deps) {
+      for (const dep of pinned.deps) {
+        if (!all.has(dep)) {
+          all.add(dep)
+          queue.push(dep)
+        }
+      }
+    }
+  }
+  return [...all]
+}
+
 /**
  * Extract import specifiers from source code
  */
@@ -156,7 +190,7 @@ export function generateImportMap(specifiers: string[]): {
 } {
   const imports: Record<string, string> = {}
 
-  for (const specifier of specifiers) {
+  for (const specifier of expandWithDeps(specifiers)) {
     imports[specifier] = getCDNUrl(specifier)
   }
 
@@ -300,7 +334,7 @@ export async function resolveImports(source: string): Promise<{
   errors: string[]
   localModules: string[]
 }> {
-  const specifiers = extractImports(source)
+  const specifiers = expandWithDeps(extractImports(source))
   const errors: string[] = []
   const imports: Record<string, string> = {}
   const localModules: string[] = []

package/demo/src/playground-shared.ts

@@ -79,6 +79,8 @@ export interface IframeDocOptions {
   parentBindings?: boolean
   /** Auto-find and call TJS-annotated functions, append DOM results */
   autoCallTjsFunction?: boolean
+  /** Whether parent is in dark mode — sets color-scheme on iframe */
+  darkMode?: boolean
 }
 
 /**
@@ -95,8 +97,11 @@ export function buildIframeDoc(options: IframeDocOptions): string {
     importStatements = [],
     parentBindings = false,
     autoCallTjsFunction = false,
+    darkMode = false,
   } = options
 
+  const colorScheme = darkMode ? 'dark' : 'light dark'
+
   const parentBindingsScript = parentBindings
     ? `
     if (parent.run) window.run = parent.run.bind(parent);
@@ -146,6 +151,7 @@ export function buildIframeDoc(options: IframeDocOptions): string {
     return `<!DOCTYPE html>
 <html>
 <head>
+  <style>:root { color-scheme: ${colorScheme} }</style>
   <style>${cssContent}</style>
   ${importMapScript}
 </head>
@@ -174,6 +180,7 @@ ${CONSOLE_CAPTURE_SCRIPT}
   return `<!DOCTYPE html>
 <html>
 <head>
+  <style>:root { color-scheme: ${colorScheme} }</style>
   <style>${cssContent}</style>
   ${importMapScript}
 </head>

package/demo/src/tjs-playground.ts

@@ -1034,6 +1034,7 @@ export class TJSPlayground extends Component<TJSPlaygroundParts> {
         importStatements,
         parentBindings: true,
         autoCallTjsFunction: true,
+        darkMode: document.body.classList.contains('darkmode'),
       })
 
       // Listen for messages from iframe

package/demo/src/ts-playground.ts

@@ -513,6 +513,7 @@ export class TSPlayground extends Component<TSPlaygroundParts> {
         htmlContent,
         importMapScript,
         jsCode,
+        darkMode: document.body.classList.contains('darkmode'),
       })
 
       // Clean up any previous message handler