tjs-lang 0.8.2 → 0.8.3

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

package/demo/src/tjs-playground.ts

@@ -43,6 +43,7 @@ import {
   buildAutocompleteContext,
   type AutocompleteContext,
 } from './autocomplete-context'
+import { IntrospectionBridge } from './introspection-bridge'
 
 // Available modules for autocomplete introspection
 const AVAILABLE_MODULES: Record<string, any> = {
@@ -166,6 +167,8 @@ export class TJSPlayground extends Component<TJSPlaygroundParts> {
   private autocompleteContext: AutocompleteContext | null = null
   private contextUpdateTimer: ReturnType<typeof setTimeout> | null = null
   private contextBuildPromise: Promise<void> | null = null
+  // Hidden sandbox for runtime-truth member completion (todoApp.items, …)
+  private introspectionBridge: IntrospectionBridge | null = null
 
   /**
    * Get metadata for autocomplete - returns all discovered functions
@@ -185,6 +188,15 @@ export class TJSPlayground extends Component<TJSPlaygroundParts> {
     return this.autocompleteContext?.bindings
   }
 
+  /**
+   * Member completion from the introspection bridge — the user's REAL executed
+   * scope (`todoApp.items` → the live array). Returns undefined if the sandbox
+   * isn't ready, so the provider falls back to static completions.
+   */
+  private getMembers = (path: string) => {
+    return this.introspectionBridge?.members(path) ?? Promise.resolve(undefined)
+  }
+
   /**
    * Update autocomplete context (debounced)
    * Called when editor content changes.
@@ -198,6 +210,14 @@ export class TJSPlayground extends Component<TJSPlaygroundParts> {
     const doBuild = async () => {
       const source = this.parts.tjsEditor.value
 
+      // Refresh the introspection sandbox (runtime-truth member completion).
+      // Independent of import-binding resolution below; failures are swallowed
+      // inside the bridge (keeps the last good sandbox).
+      if (!this.introspectionBridge) {
+        this.introspectionBridge = new IntrospectionBridge()
+      }
+      void this.introspectionBridge.refresh(source)
+
       try {
         const newContext = await buildAutocompleteContext(source)
         // Only update if we got bindings (keep last good context otherwise)
@@ -649,6 +669,7 @@ export class TJSPlayground extends Component<TJSPlaygroundParts> {
       this.parts.tjsEditor.autocomplete = {
         getMetadata: this.getMetadataForAutocomplete,
         getLiveBindings: this.getLiveBindings,
+        getMembers: this.getMembers,
       }
 
       // Build initial autocomplete context immediately

package/editors/codemirror/ajs-language.ts

@@ -50,6 +50,8 @@ import {
   FORBIDDEN_PATTERN,
 } from '../ajs-syntax'
 import { FORBIDDEN_KEYWORDS as TJS_FORBIDDEN_LIST } from '../tjs-syntax'
+import { collectScopeSymbols } from '../scope-symbols'
+import type { IntrospectMember } from '../introspect-value'
 
 /**
  * Forbidden keywords in AsyncJS - these will be highlighted as errors
@@ -341,6 +343,26 @@ export interface AutocompleteConfig {
    * e.g., { elements: Proxy, div: HTMLDivElement }
    */
   getLiveBindings?: () => Record<string, any> | undefined
+  /**
+   * Async member completion from the introspection bridge: given a dotted path
+   * (`todoApp.items`), returns the value's REAL runtime members from the user's
+   * executed scope in a sandbox — including proxy-generated ones nothing static
+   * can see. Used as a fallback when the path doesn't resolve in sync bindings.
+   */
+  getMembers?: (path: string) => Promise<IntrospectMember[] | undefined>
+}
+
+/** Map a serializable introspection member into a CodeMirror completion. */
+function memberToCompletion(m: IntrospectMember): CMCompletion {
+  if (m.type === 'method') {
+    const hasArgs = m.detail !== '()'
+    return snippetCompletion(`${m.label}(${hasArgs ? '${1}' : ''})`, {
+      label: m.label,
+      type: 'method',
+      detail: m.detail,
+    })
+  }
+  return { label: m.label, type: 'property', detail: m.detail }
 }
 
 // TJS keywords with snippets
@@ -616,6 +638,41 @@ function extractVariables(source: string, position: number): CMCompletion[] {
   return completions
 }
 
+/**
+ * Scope-aware locals: replaces the regex `extractFunctions`/`extractVariables`
+ * (which missed ALL destructuring — and the tosijs examples bind everything via
+ * destructuring, so nothing was suggested). Parses with acorn (acorn-loose
+ * fallback for mid-edit source) and walks binding patterns. Falls back to the
+ * regex extractors only if parsing yields nothing, so the list never goes blank.
+ */
+function completionsFromScope(
+  source: string,
+  position: number
+): CMCompletion[] {
+  const symbols = collectScopeSymbols(source, position)
+  if (symbols.length === 0) {
+    return [...extractFunctions(source), ...extractVariables(source, position)]
+  }
+  return symbols.map((s) => {
+    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
+    if (s.kind === 'function') {
+      return snippetCompletion(`${s.name}($1)`, {
+        label: s.name,
+        type: 'function',
+        detail,
+      })
+    }
+    return { label: s.name, type: 'variable', detail }
+  })
+}
+
 /**
  * Curated property completions for common globals
  * These are hand-picked for usefulness with proper type signatures
@@ -1203,7 +1260,7 @@ function introspectObject(obj: any): CMCompletion[] {
 
         if (valueType === 'function') {
           // Try to get function signature from length
-          const fn = value as Function
+          const fn = value as (...args: unknown[]) => unknown
           const paramCount = fn.length
           const params =
             paramCount > 0
@@ -1263,32 +1320,9 @@ function getCompletionsFromLiveBinding(
   name: string,
   liveBindings?: Record<string, any>
 ): CMCompletion[] {
-  // Debug: log what we're looking for and what we have
-  console.debug(
-    '[autocomplete] Looking for:',
-    name,
-    'in bindings:',
-    liveBindings ? Object.keys(liveBindings) : 'none'
-  )
-
   // First, check if we have a live binding for this name
   if (liveBindings && name in liveBindings) {
-    const value = liveBindings[name]
-    console.debug(
-      '[autocomplete] Found binding:',
-      name,
-      '=',
-      value,
-      'type:',
-      typeof value
-    )
-    const completions = introspectObject(value)
-    console.debug(
-      '[autocomplete] Introspection returned',
-      completions.length,
-      'completions'
-    )
-    return completions
+    return introspectObject(liveBindings[name])
   }
 
   // Special case: if the name looks like it could be an HTML element variable,
@@ -1328,14 +1362,54 @@ function getCompletionsFromLiveBinding(
 }
 
 /**
- * Extract the object name before a dot from source
- * e.g., "console." -> "console", "Math.floor" -> "Math"
+ * Extract the full dotted member path before a dot, e.g. `todoApp.items.` ->
+ * `todoApp.items`. Only plain identifier chains (no calls / index access) — good
+ * enough to walk a live value for member completion.
  */
-function getObjectBeforeDot(source: string, dotPos: number): string | null {
-  // Look backwards from the dot to find the identifier
+function getPathBeforeDot(source: string, dotPos: number): string | null {
   const before = source.slice(0, dotPos)
-  const match = before.match(/(\w+)\s*$/)
-  return match ? match[1] : null
+  const match = before.match(
+    /([A-Za-z_$][\w$]*(?:\s*\.\s*[A-Za-z_$][\w$]*)*)\s*$/
+  )
+  return match ? match[1].replace(/\s+/g, '') : null
+}
+
+/** Walk a dotted path against a bindings object, returning the resolved value. */
+function resolvePath(path: string, bindings?: Record<string, any>): any {
+  if (!bindings) return undefined
+  const parts = path.split('.')
+  let value: any = bindings[parts[0]]
+  for (let i = 1; i < parts.length && value != null; i++) {
+    try {
+      value = value[parts[i]]
+    } catch {
+      return undefined
+    }
+  }
+  return value
+}
+
+/**
+ * Member completions for a dotted path resolved against live bindings — the
+ * core of introspection-driven completion. `todoApp.items.` resolves the array
+ * and introspects it (push/map/…). Single-segment names that don't resolve fall
+ * back to the element-type heuristic.
+ */
+function getCompletionsFromPath(
+  path: string,
+  liveBindings?: Record<string, any>
+): CMCompletion[] {
+  const value = resolvePath(path, liveBindings)
+  if (
+    value != null &&
+    (typeof value === 'object' || typeof value === 'function')
+  ) {
+    return introspectObject(value)
+  }
+  if (!path.includes('.')) {
+    return getCompletionsFromLiveBinding(path, liveBindings)
+  }
+  return []
 }
 
 /**
@@ -1395,10 +1469,13 @@ function getPlaceholderForParam(name: string, info: any): string {
 }
 
 /**
- * Create TJS/AJS completion source
+ * Create TJS/AJS completion source.
+ * Exported for headless testing — it touches only DOM-free CodeMirror APIs.
  */
-function tjsCompletionSource(config: AutocompleteConfig = {}) {
-  return (context: CMCompletionContext): CompletionResult | null => {
+export function tjsCompletionSource(config: AutocompleteConfig = {}) {
+  return async (
+    context: CMCompletionContext
+  ): Promise<CompletionResult | null> => {
     try {
       // Get word at cursor
       const word = context.matchBefore(/[\w$]*/)
@@ -1434,16 +1511,26 @@ function tjsCompletionSource(config: AutocompleteConfig = {}) {
         if (/expect\s*\([^)]*\)\s*\.$/.test(before)) {
           options = EXPECT_MATCHERS
         } else {
-          // Try to get object name and introspect its properties
-          const objName = getObjectBeforeDot(source, word.from - 1)
-          if (objName) {
-            // First try curated/global completions
-            options = getPropertyCompletions(objName)
-
-            // If no completions found, try live bindings (imports, variables)
+          // Resolve the full dotted path so `todoApp.items.` works, not just
+          // `todoApp.`. Curated/global completions are keyed by a single name.
+          const path = getPathBeforeDot(source, word.from - 1)
+          if (path) {
+            if (!path.includes('.')) {
+              options = getPropertyCompletions(path)
+            }
+            // Then introspect the live value the path resolves to in the sync
+            // bindings (resolved imports).
             if (options.length === 0) {
               const liveBindings = config.getLiveBindings?.()
-              options = getCompletionsFromLiveBinding(objName, liveBindings)
+              options = getCompletionsFromPath(path, liveBindings)
+            }
+            // Finally, the introspection bridge: the user's REAL executed scope
+            // (`todoApp.items` → the live array's members), incl. proxy members.
+            if (options.length === 0 && config.getMembers) {
+              const members = await config.getMembers(path)
+              if (members && members.length) {
+                options = members.map(memberToCompletion)
+              }
             }
           }
         }
@@ -1462,8 +1549,7 @@ function tjsCompletionSource(config: AutocompleteConfig = {}) {
           ...TJS_COMPLETIONS,
           ...RUNTIME_COMPLETIONS,
           ...GLOBAL_COMPLETIONS,
-          ...extractFunctions(source),
-          ...extractVariables(source, pos),
+          ...completionsFromScope(source, pos),
         ]
 
         // Add metadata-based completions if available