tjs-lang 0.8.1 → 0.8.3

package/demo/examples.test.ts

@@ -448,9 +448,13 @@ describe('Playground Examples', () => {
             args.imageUrl = '/test-shapes.jpg'
           }
 
-          // Use the SAME capabilities as the playground
+          // Use the SAME capabilities as the playground.
+          // Vision inference on a local model can take a while; give it an
+          // explicit budget well above the slow-atom timeout so the test is
+          // deterministic regardless of the run-level default.
           const runResult = await vm.run(result.ast, args, {
             fuel: 100000,
+            timeoutMs: 180000,
             capabilities: {
               fetch: httpFetch,
               llm: llmCapability || mockLLM,
@@ -466,7 +470,7 @@ describe('Playground Examples', () => {
         } finally {
           trackTestEnd()
         }
-      }, 120000)
+      }, 240000) // bun-test timeout above the vm timeoutMs (180s) + overhead
     } else if (needsRetry) {
       // Examples that use runCode need retry due to LLM variability
       it(`${example.name} - runs successfully`, async () => {

package/demo/src/autocomplete.ts

@@ -5,6 +5,11 @@
  * Uses __tjs metadata for rich type information.
  */
 
+import {
+  collectScopeSymbols,
+  type ScopeSymbol,
+} from '../../editors/scope-symbols'
+
 export interface Completion {
   /** The text to insert */
   label: string
@@ -277,6 +282,40 @@ function isInTestBlock(source: string, position: number): boolean {
   return testMatches.length > 0
 }
 
+/**
+ * Completions from the scope-aware symbol model (acorn-based, destructuring-aware).
+ * Subsumes the old regex `extractFunctions`/`extractVariables`, which missed all
+ * destructuring. Falls back to the regex extractors only if parsing yields
+ * nothing (so the list never goes blank on pathological input).
+ */
+function completionsFromScope(source: string, position: number): Completion[] {
+  const symbols = collectScopeSymbols(source, position)
+  if (symbols.length === 0) {
+    return [...extractFunctions(source), ...extractVariables(source, position)]
+  }
+  return symbols.map((s) => scopeSymbolToCompletion(s))
+}
+
+function scopeSymbolToCompletion(s: ScopeSymbol): Completion {
+  const kind: Completion['kind'] =
+    s.kind === 'function' ? 'function' : 'variable'
+  // For a destructured binding, show where it came from — `h1  ∈ elements`.
+  const detail =
+    s.origin?.member && s.origin.expr
+      ? `∈ ${s.origin.expr}`
+      : s.kind === 'import' && s.origin?.module
+      ? `import '${s.origin.module}'`
+      : s.kind === 'parameter'
+      ? 'parameter'
+      : undefined
+  return {
+    label: s.name,
+    kind,
+    detail,
+    snippet: kind === 'function' ? `${s.name}($1)` : undefined,
+  }
+}
+
 /**
  * Extract function names from source
  */
@@ -418,8 +457,7 @@ export function getCompletions(ctx: CompletionContext): Completion[] {
     completions = [
       ...TJS_KEYWORDS,
       ...RUNTIME_COMPLETIONS,
-      ...extractFunctions(source),
-      ...extractVariables(source, position),
+      ...completionsFromScope(source, position),
     ]
 
     // Add metadata-based completions

package/demo/src/introspection-bridge.ts

@@ -0,0 +1,140 @@
+/**
+ * Introspection bridge — the runtime-truth half of the autocomplete plan.
+ *
+ * Chrome-console style: run the user's code in a hidden, disposable sandbox
+ * iframe and keep a live `eval` handle into its module scope. Member completion
+ * (`todoApp.items.` → the real array's members; `elements.` → tosijs's
+ * proxy-generated creators) then comes from the ACTUAL values, not a static
+ * model. The sandbox reuses the playground's run pipeline (transpile →
+ * rewriteImports → buildIframeDoc → SW-served URL) so imports resolve the same
+ * way the preview does.
+ *
+ * Lifecycle: `refresh(source)` rebuilds the sandbox (debounced by the caller, on
+ * statement boundaries) and caches the last good one — if the source doesn't
+ * transpile, the previous sandbox stays queryable. `members(path)` asks the
+ * sandbox to introspect a value, with a short timeout so the editor never hangs.
+ */
+import { tjs } from '../../src/lang'
+import { rewriteImports, registerIframeContent } from './imports'
+import { buildIframeDoc } from './playground-shared'
+import type { IntrospectMember } from '../../editors/introspect-value'
+
+export class IntrospectionBridge {
+  private iframe: HTMLIFrameElement
+  private ready = false
+  private lastSource: string | null = null
+  private pending = new Map<number, (members: IntrospectMember[]) => void>()
+  private nextId = 1
+  private readonly onMessage: (e: MessageEvent) => void
+
+  constructor() {
+    const iframe = document.createElement('iframe')
+    iframe.setAttribute('aria-hidden', 'true')
+    iframe.setAttribute('tabindex', '-1')
+    // Off-screen and inert, but still a real DOM so tosijs `elements` work.
+    iframe.style.cssText =
+      'position:absolute;width:1px;height:1px;left:-9999px;top:-9999px;border:0;visibility:hidden;pointer-events:none;'
+    document.body.appendChild(iframe)
+    this.iframe = iframe
+
+    this.onMessage = (e: MessageEvent) => {
+      const d = e.data
+      if (!d || e.source !== iframe.contentWindow) return
+      if (d.type === 'tjs-bridge-ready') {
+        this.ready = true
+      } else if (d.type === 'tjs-introspect-result') {
+        const resolve = this.pending.get(d.id)
+        if (resolve) {
+          this.pending.delete(d.id)
+          resolve(Array.isArray(d.members) ? d.members : [])
+        }
+      }
+    }
+    window.addEventListener('message', this.onMessage)
+  }
+
+  /**
+   * Rebuild the sandbox from the current source. No-op if unchanged or if the
+   * source doesn't transpile (keeps the last good sandbox). Caller should
+   * debounce this to statement boundaries.
+   */
+  async refresh(source: string): Promise<void> {
+    if (source === this.lastSource) return
+
+    let code: string
+    try {
+      const result = tjs(source)
+      code = result.code
+    } catch {
+      return // not transpilable yet — keep the last good sandbox
+    }
+    this.lastSource = source
+
+    const rewritten = rewriteImports(code)
+    const importStatements: string[] = []
+    const body = rewritten.replace(
+      /^import\s+(?:.*?from\s+)?['"][^'"]+['"];?\s*$/gm,
+      (match) => {
+        importStatements.push(match)
+        return ''
+      }
+    )
+
+    const doc = buildIframeDoc({
+      cssContent: '',
+      htmlContent: '',
+      importMapScript: '',
+      jsCode: body,
+      importStatements,
+      introspectionBridge: true,
+    })
+
+    this.ready = false
+    // Reject in-flight queries against the old sandbox.
+    for (const resolve of this.pending.values()) resolve([])
+    this.pending.clear()
+
+    const sessionId = `tjs-introspect-${Date.now()}-${Math.random()
+      .toString(36)
+      .slice(2)}`
+    const registered = await registerIframeContent(sessionId, doc)
+    if (registered) {
+      this.iframe.src = `/iframe/${sessionId}`
+    } else {
+      const blob = new Blob([doc], { type: 'text/html' })
+      this.iframe.src = URL.createObjectURL(blob)
+    }
+  }
+
+  /**
+   * Introspect a dotted path in the live sandbox scope. Resolves to the value's
+   * real members, or `undefined` if the sandbox isn't ready / times out (so the
+   * caller can fall back to static completions).
+   */
+  members(
+    path: string,
+    timeoutMs = 500
+  ): Promise<IntrospectMember[] | undefined> {
+    const win = this.iframe.contentWindow
+    if (!this.ready || !win) return Promise.resolve(undefined)
+
+    const id = this.nextId++
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id)
+        resolve(undefined)
+      }, timeoutMs)
+      this.pending.set(id, (members) => {
+        clearTimeout(timer)
+        resolve(members)
+      })
+      win.postMessage({ type: 'tjs-introspect', id, path }, '*')
+    })
+  }
+
+  dispose(): void {
+    window.removeEventListener('message', this.onMessage)
+    this.iframe.remove()
+    this.pending.clear()
+  }
+}

package/demo/src/introspection-doc.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'bun:test'
+
+// buildIframeDoc reads location.origin (browser global) — stub it for headless.
+;(globalThis as any).location ??= { origin: 'http://test' }
+
+import { buildIframeDoc } from './playground-shared'
+
+/**
+ * Structural guard for the introspection sandbox document. The critical
+ * invariant: user code must run at MODULE TOP LEVEL (not inside a try block) so
+ * its top-level `const`/`let` are module-scoped and the bridge's direct `eval`
+ * can see them. A regression here silently breaks `todoApp.` completion.
+ */
+describe('buildIframeDoc — introspection bridge document', () => {
+  const doc = buildIframeDoc({
+    cssContent: '',
+    htmlContent: '',
+    importMapScript: '',
+    jsCode: 'const todoApp = { items: [] }',
+    importStatements: ["import { tosi } from 'https://cdn/tosijs'"],
+    introspectionBridge: true,
+  })
+
+  it('runs user code at module top level — NOT inside a try block', () => {
+    expect(doc).toContain('const todoApp = { items: [] }')
+    // The real invariant: after the bridge is installed, the user code runs with
+    // no try-wrap between (a block would re-scope its declarations away from
+    // eval). (The injected introspector has its own internal try/catch — that's
+    // fine and lives before the ready post.)
+    const readyIdx = doc.indexOf('tjs-bridge-ready')
+    const codeIdx = doc.indexOf('const todoApp')
+    expect(codeIdx).toBeGreaterThan(readyIdx)
+    expect(doc.slice(readyIdx, codeIdx)).not.toContain('try {')
+  })
+
+  it('installs the message listener and the injected introspector', () => {
+    expect(doc).toContain("d.type !== 'tjs-introspect'")
+    expect(doc).toContain('eval(d.path)')
+    expect(doc).toContain('function introspectValue') // injected source
+  })
+
+  it('posts bridge-ready and puts imports first', () => {
+    expect(doc).toContain('tjs-bridge-ready')
+    const importIdx = doc.indexOf('import { tosi }')
+    const listenerIdx = doc.indexOf('tjs-introspect')
+    const codeIdx = doc.indexOf('const todoApp')
+    // imports → listener → user code
+    expect(importIdx).toBeGreaterThan(-1)
+    expect(importIdx).toBeLessThan(listenerIdx)
+    expect(listenerIdx).toBeLessThan(codeIdx)
+  })
+
+  it('does not install the bridge for a normal preview doc', () => {
+    const preview = buildIframeDoc({
+      cssContent: '',
+      htmlContent: '',
+      importMapScript: '',
+      jsCode: 'console.log(1)',
+    })
+    expect(preview).not.toContain('tjs-introspect')
+    expect(preview).toContain('try {') // normal preview DOES wrap in try
+  })
+})

package/demo/src/playground-shared.ts

@@ -6,6 +6,7 @@
  */
 
 import type { CodeMirror } from '../../editors/codemirror/component'
+import { INTROSPECT_VALUE_SOURCE } from '../../editors/introspect-value'
 
 // ---------------------------------------------------------------------------
 // TJS Runtime for iframe — loaded from a built file, not a hand-maintained stub.
@@ -48,6 +49,32 @@ export interface IframeDocOptions {
   autoCallTjsFunction?: boolean
   /** Whether parent is in dark mode — sets color-scheme on iframe */
   darkMode?: boolean
+  /**
+   * Install the introspection bridge: after the user's code runs, a message
+   * listener answers `{type:'tjs-introspect', id, path}` by evaluating `path` in
+   * module scope and returning the value's real members. Used by the hidden
+   * autocomplete sandbox (IntrospectionBridge), not the visible preview.
+   */
+  introspectionBridge?: boolean
+}
+
+/**
+ * Script (injected at module top-level, after the user's code) that answers
+ * member-introspection queries from the parent. `eval(path)` is a DIRECT eval in
+ * the module's lexical scope, so it sees the user's top-level `const`/`let`
+ * bindings (e.g. `todoApp.items`). Runs only in the hidden sandbox.
+ */
+function introspectionBridgeScript(): string {
+  return `
+    const __introspectValue = ${INTROSPECT_VALUE_SOURCE};
+    window.addEventListener('message', (e) => {
+      const d = e.data;
+      if (!d || d.type !== 'tjs-introspect') return;
+      let members = [];
+      try { members = __introspectValue(eval(d.path)); } catch (_e) {}
+      parent.postMessage({ type: 'tjs-introspect-result', id: d.id, members }, '*');
+    });
+    parent.postMessage({ type: 'tjs-bridge-ready' }, '*');`
 }
 
 /**
@@ -68,8 +95,34 @@ export function buildIframeDoc(options: IframeDocOptions): string {
     parentBindings = false,
     autoCallTjsFunction = false,
     darkMode = false,
+    introspectionBridge = false,
   } = options
 
+  // Introspection sandbox: run user code at MODULE TOP LEVEL (no try-wrap) so
+  // top-level `const`/`let` are module-scoped and the bridge's direct `eval` can
+  // see them. The listener is installed first; it's invoked later (at query
+  // time), by when the module — and `todoApp` — has fully initialised. Ready is
+  // posted up front so globals/imports stay introspectable even if user code
+  // throws partway. No try/catch precisely because a block would re-scope the
+  // declarations away from `eval`.
+  if (introspectionBridge) {
+    return `<!DOCTYPE html>
+<html>
+<head>
+  <style>:root { color-scheme: ${darkMode ? 'dark' : 'light dark'} }</style>
+  ${importMapScript}
+</head>
+<body>
+  ${runtimeScriptTag}
+  <script type="module">
+    ${importStatements.join('\n    ')}
+${introspectionBridgeScript()}
+    ${jsCode}
+  </script>
+</body>
+</html>`
+  }
+
   const colorScheme = darkMode ? 'dark' : 'light dark'
 
   const parentBindingsScript = parentBindings
@@ -255,28 +308,36 @@ export function renderConsoleMessages(
 
 /**
  * Render test results HTML with clickable error links and editor gutter markers.
- * Returns pass/fail counts so callers can update tab indicators.
+ * Returns pass/fail/inconclusive counts so callers can update tab indicators.
  */
 export function renderTestResults(
   tests: any[],
   outputEl: HTMLElement,
   editor: CodeMirror,
   goToLine: (line: number) => void
-): { passed: number; failed: number } {
+): { passed: number; failed: number; inconclusive: number } {
   if (!tests || tests.length === 0) {
     outputEl.textContent = 'No tests defined'
     editor.clearMarkers()
-    return { passed: 0, failed: 0 }
+    return { passed: 0, failed: 0, inconclusive: 0 }
   }
 
   const passed = tests.filter((t: any) => t.passed).length
-  const failed = tests.filter((t: any) => !t.passed).length
-
-  // Mark only FAILED tests in the editor. Passing tests appear in the
-  // results panel and don't need an underline — `severity: 'info'` was
-  // rendering as a grey squiggle on every passing test's line, which is
-  // visual noise.
-  const failedWithLines = tests.filter((t: any) => t.line && !t.passed)
+  // Inconclusive = the test couldn't *run* (e.g. it calls an AJS atom that
+  // doesn't exist at build time). It is neither pass nor fail — surface it as
+  // a distinct warning state and keep it out of the failure count, so legal
+  // AJS doesn't read as broken in the playground. See PRINCIPLES.md.
+  const inconclusive = tests.filter(
+    (t: any) => !t.passed && t.inconclusive
+  ).length
+  const failed = tests.filter((t: any) => !t.passed && !t.inconclusive).length
+
+  // Mark only genuine FAILURES in the editor. Passing tests don't need an
+  // underline (it reads as visual noise), and an inconclusive test isn't a
+  // failure — a red squiggle would wrongly imply the code is broken.
+  const failedWithLines = tests.filter(
+    (t: any) => t.line && !t.passed && !t.inconclusive
+  )
   if (failedWithLines.length > 0) {
     editor.setMarkers(
       failedWithLines.map((t: any) => ({
@@ -294,19 +355,29 @@ export function renderTestResults(
   if (failed > 0) {
     html += `, <strong class="test-failed">${failed} failed</strong>`
   }
+  if (inconclusive > 0) {
+    html += `, <strong class="test-inconclusive">${inconclusive} inconclusive</strong>`
+  }
   html += `</div><ul class="test-list">`
 
   for (const test of tests) {
-    const icon = test.passed ? '✓' : '✗'
-    const cls = test.passed ? 'test-pass' : 'test-fail'
+    const state = test.passed
+      ? 'pass'
+      : test.inconclusive
+      ? 'inconclusive'
+      : 'fail'
+    const icon = test.passed ? '✓' : test.inconclusive ? '—' : '✗'
     const sigBadge = test.isSignatureTest
       ? ' <span class="sig-badge">signature</span>'
       : ''
     const dataLine = test.line ? ` data-line="${test.line}"` : ''
     const clickable = test.line ? ' clickable-test' : ''
-    html += `<li class="${cls}${clickable}"${dataLine}>${icon} ${test.description}${sigBadge}`
-    if (!test.passed && test.error) {
-      html += `<div class="test-error">${test.error}</div>`
+    html += `<li class="test-${state}${clickable}"${dataLine}>${icon} ${test.description}${sigBadge}`
+    if (test.error) {
+      // Inconclusive notes are warnings (couldn't run), not failures.
+      const noteCls = test.inconclusive ? 'test-note' : 'test-error'
+      const prefix = test.inconclusive ? 'could not run — ' : ''
+      html += `<div class="${noteCls}">${prefix}${test.error}</div>`
     }
     html += `</li>`
   }
@@ -327,7 +398,7 @@ export function renderTestResults(
     })
   })
 
-  return { passed, failed }
+  return { passed, failed, inconclusive }
 }
 
 // ---------------------------------------------------------------------------
@@ -589,6 +660,20 @@ export const sharedPlaygroundStyles: Record<string, Record<string, string>> = {
     fontFamily: 'var(--font-mono, monospace)',
   },
 
+  ':host .test-inconclusive': {
+    color: '#d97706',
+  },
+
+  ':host .test-note': {
+    marginLeft: '20px',
+    marginTop: '4px',
+    padding: '8px',
+    background: 'rgba(217, 119, 6, 0.1)',
+    borderRadius: '4px',
+    fontSize: '13px',
+    fontFamily: 'var(--font-mono, monospace)',
+  },
+
   ':host .clickable-test': {
     cursor: 'pointer',
   },

package/demo/src/playground-test-results.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect, beforeAll, afterAll } from 'bun:test'
+import { GlobalRegistrator } from '@happy-dom/global-registrator'
+
+beforeAll(() => GlobalRegistrator.register())
+afterAll(() => GlobalRegistrator.unregister())
+
+// Imported after DOM globals exist.
+const { renderTestResults } = await import('./playground-shared')
+
+function fakeEditor() {
+  const calls: any[] = []
+  return {
+    setMarkers: (m: any) => calls.push({ setMarkers: m }),
+    clearMarkers: () => calls.push({ clearMarkers: true }),
+    _calls: calls,
+  } as any
+}
+
+describe('renderTestResults — inconclusive affordance', () => {
+  it('separates inconclusive from passed and failed', () => {
+    const out = document.createElement('div')
+    const editor = fakeEditor()
+    const counts = renderTestResults(
+      [
+        { description: 'a', passed: true },
+        { description: 'b', passed: false, error: 'Expected 5 got 6' },
+        {
+          description: 'c signature example',
+          passed: false,
+          inconclusive: true,
+          isSignatureTest: true,
+          error: 'httpFetch is not defined',
+        },
+      ],
+      out,
+      editor,
+      () => {}
+    )
+
+    expect(counts).toEqual({ passed: 1, failed: 1, inconclusive: 1 })
+
+    // Summary shows all three states
+    expect(out.querySelector('.test-summary')?.textContent).toContain(
+      '1 passed'
+    )
+    expect(out.querySelector('.test-summary')?.textContent).toContain(
+      '1 failed'
+    )
+    expect(out.querySelector('.test-summary')?.textContent).toContain(
+      '1 inconclusive'
+    )
+
+    // The inconclusive test renders with its own class + a warning note (not
+    // a red error), with the "could not run" framing.
+    const incLi = out.querySelector('li.test-inconclusive')
+    expect(incLi).not.toBeNull()
+    expect(incLi?.textContent).toContain('—') // not the ✗ failure icon
+    expect(incLi?.querySelector('.test-note')).not.toBeNull()
+    expect(incLi?.querySelector('.test-error')).toBeNull()
+    expect(incLi?.querySelector('.test-note')?.textContent).toContain(
+      'could not run'
+    )
+
+    // The genuine failure keeps the red error box + ✗ icon.
+    const failLi = out.querySelector('li.test-fail')
+    expect(failLi?.textContent).toContain('✗')
+    expect(failLi?.querySelector('.test-error')).not.toBeNull()
+  })
+
+  it('renders REAL transpiler output: atom-calling agent → inconclusive', async () => {
+    // End-to-end: the transpiler emits inconclusive for an un-runnable
+    // signature test; the playground must render it as such (not a failure).
+    const { tjs } = await import('../../src/lang')
+    const { testResults } = tjs(
+      `function main(url: ''): { x: '' } {\n  const x = httpFetch({ url })\n  return { x }\n}`
+    )
+    const out = document.createElement('div')
+    const counts = renderTestResults(
+      testResults as any,
+      out,
+      fakeEditor(),
+      () => {}
+    )
+    expect(counts.failed).toBe(0)
+    expect(counts.inconclusive).toBe(1)
+    expect(out.querySelector('li.test-inconclusive')).not.toBeNull()
+    expect(out.querySelector('li.test-fail')).toBeNull()
+  })
+
+  it('does NOT put an error marker on an inconclusive test line', () => {
+    const out = document.createElement('div')
+    const editor = fakeEditor()
+    renderTestResults(
+      [
+        {
+          description: 'sig',
+          passed: false,
+          inconclusive: true,
+          line: 3,
+          error: 'atom not defined',
+        },
+      ],
+      out,
+      editor,
+      () => {}
+    )
+    // No setMarkers with an error for the inconclusive line; clearMarkers instead.
+    const markerCalls = editor._calls.filter((c: any) => c.setMarkers)
+    expect(markerCalls).toHaveLength(0)
+    expect(editor._calls.some((c: any) => c.clearMarkers)).toBe(true)
+  })
+})