tjs-lang 0.8.4 → 0.8.6

package/llms.txt

@@ -44,6 +44,8 @@ This file is a navigation index for AI agents. It does not contain the docs them
 - `tjs-lang` → `src/index.ts` — main entry: `Agent`, `AgentVM`, `ajs`, `tjs`.
 - `tjs-lang/lang` → `src/lang/transpiler.ts` — language tools only: `tjs`, `transpile`.
 - `tjs-lang/lang/from-ts` → `src/lang/emitters/from-ts.ts` — TypeScript → TJS/JS transpilation.
+- `tjs-lang/browser` → `src/lang/browser.ts` (dist `tjs-browser.js`) — **self-contained** TJS/AJS transpiler (acorn + tosijs-schema inlined); `import()` from any CDN, zero config.
+- `tjs-lang/browser/from-ts` → `src/lang/browser-from-ts.ts` (dist `tjs-browser-from-ts.js`) — browser TS→TJS; lazy-loads the `typescript` compiler from a CDN (default `https://esm.sh/typescript@5` — the only CDN that serves it reliably; jsDelivr `+esm`/esm.run time out). Override with `fromTS(src, { typescriptUrl })` or preload `globalThis.__TJS_TS__`.
 - `tjs-lang/vm` → `src/vm/index.ts` — VM and atoms.
 - `tjs-lang/eval` → `src/lang/eval.ts` — `Eval`, `SafeFunction`.
 - `tjs-lang/batteries` → `src/batteries/index.ts` — LM Studio integration (lazy, local-only).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tjs-lang",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "description": "Type-safe JavaScript dialect with runtime validation, sandboxed VM execution, and AI agent orchestration. Transpiles TypeScript to validated JS with fuel-metered execution for untrusted code.",
   "keywords": [
     "typescript",
@@ -33,6 +33,12 @@
       "lang/from-ts": [
         "./dist/src/lang/emitters/from-ts.d.ts"
       ],
+      "browser": [
+        "./dist/src/lang/browser.d.ts"
+      ],
+      "browser/from-ts": [
+        "./dist/src/lang/browser-from-ts.d.ts"
+      ],
       "vm": [
         "./dist/src/vm/index.d.ts"
       ],
@@ -62,6 +68,14 @@
       "types": "./dist/src/lang/emitters/from-ts.d.ts",
       "default": "./dist/tjs-from-ts.js"
     },
+    "./browser": {
+      "types": "./dist/src/lang/browser.d.ts",
+      "default": "./dist/tjs-browser.js"
+    },
+    "./browser/from-ts": {
+      "types": "./dist/src/lang/browser-from-ts.d.ts",
+      "default": "./dist/tjs-browser-from-ts.js"
+    },
     "./vm": {
       "bun": "./src/vm/index.ts",
       "types": "./dist/src/vm/index.d.ts",

package/src/lang/browser-bundle.test.ts

@@ -0,0 +1,69 @@
+/**
+ * Guards the browser bundles' defining property: they must be **self-contained**
+ * (no bare/node imports) so a single `import('https://cdn/.../tjs-browser.js')`
+ * works on any CDN with zero import-map/config. Builds in-test with esbuild, so
+ * it doesn't depend on `dist/` existing.
+ *
+ * CDN reality (verified in a real headless browser, 2026-06): the self-contained
+ * TJS/AJS bundle loads from ANY CDN; for the TypeScript path, the compiler is
+ * lazy-loaded and **esm.sh is the only CDN that reliably serves `typescript`**
+ * (jsDelivr `+esm` / esm.run time out on its ~10MB CJS; skypack is dead).
+ */
+import { describe, it, expect } from 'bun:test'
+import { buildSync } from 'esbuild'
+import { DEFAULT_TYPESCRIPT_URL } from './browser-from-ts'
+
+const HERE = import.meta.dir
+
+function bundle(entry: string, alias?: Record<string, string>): string {
+  const r = buildSync({
+    entryPoints: [`${HERE}/${entry}`],
+    bundle: true,
+    format: 'esm',
+    platform: 'neutral',
+    write: false,
+    external: [],
+    alias,
+  })
+  return r.outputFiles[0].text
+}
+
+/** Bare (non-relative, non-URL) static + dynamic import specifiers. */
+function bareImports(src: string): string[] {
+  const found: string[] = []
+  for (const m of src.matchAll(
+    /(?:^|[;\n}])import\s*(?:[^"';]*?from)?\s*["']([^"']+)["']/g
+  ))
+    found.push(m[1])
+  for (const m of src.matchAll(/import\(\s*["']([^"']+)["']\s*\)/g))
+    found.push(m[1])
+  return [...new Set(found)].filter(
+    (s) => !s.startsWith('.') && !s.startsWith('http')
+  )
+}
+
+describe('browser bundles are self-contained (CDN drop-in)', () => {
+  it('tjs-browser inlines all deps — no bare/node imports', () => {
+    const out = bundle('browser.ts')
+    // bareImports([]) already implies no `node:` imports (they'd be bare too);
+    // a raw `out.includes('node:')` would false-positive on `{node: ...}` props.
+    expect(bareImports(out)).toEqual([])
+    // sanity: acorn really got inlined (parser internals present)
+    expect(out.length).toBeGreaterThan(100_000)
+  })
+
+  it('tjs-browser-from-ts: no bare imports, TS lazy (not inlined)', () => {
+    const out = bundle('browser-from-ts.ts', {
+      typescript: `${HERE}/ts-cdn-shim.ts`,
+    })
+    expect(bareImports(out)).toEqual([])
+    // typescript must NOT be bundled in (it's ~10MB) — the shim swaps it out
+    expect(out.length).toBeLessThan(300_000)
+    // the only runtime dependency is the configurable compiler URL
+    expect(out).toContain('esm.sh/typescript')
+  })
+
+  it('default TypeScript CDN is esm.sh (the only one that serves it reliably)', () => {
+    expect(DEFAULT_TYPESCRIPT_URL).toBe('https://esm.sh/typescript@5')
+  })
+})

package/src/lang/browser-from-ts.ts

@@ -0,0 +1,81 @@
+/**
+ * Browser TypeScript→TJS — lazy-loads the TypeScript compiler from a CDN on
+ * demand, so the bundle stays small and only pays the (~MB) compiler download
+ * when you actually transpile TS. `acorn` + `tosijs-schema` are bundled in; the
+ * `typescript` import in `from-ts.ts` is aliased (at build time) to a Proxy that
+ * forwards to the lazily-loaded compiler (see `ts-cdn-shim.ts`).
+ *
+ *   const { fromTS } = await import('https://cdn.jsdelivr.net/npm/tjs-lang/dist/tjs-browser-from-ts.js')
+ *   const { code } = await fromTS('const x: number = 1', { emitTJS: true })
+ *
+ * Zero config by default. Override the compiler source with `typescriptUrl` (or
+ * preload it yourself onto `globalThis.__TJS_TS__`).
+ */
+import type { FromTSOptions, FromTSResult } from './emitters/from-ts'
+
+/**
+ * Default CDN for the TypeScript compiler. **esm.sh** — verified the only CDN
+ * that reliably serves `typescript` as ESM (default export = the compiler
+ * namespace), in ~700ms. The on-the-fly bundlers choke on typescript's ~10MB
+ * CommonJS size: jsDelivr `+esm`, esm.run → timeout; skypack → dead. So esm.sh
+ * it is. Override via `BrowserFromTSOptions.typescriptUrl` (e.g. a self-hosted
+ * copy) or preload your own compiler onto `globalThis.__TJS_TS__`.
+ *
+ * NOTE: only the *TypeScript* path depends on this. The TJS/AJS transpiler
+ * (`tjs-lang/browser`) is fully self-contained and loads from ANY CDN.
+ */
+export const DEFAULT_TYPESCRIPT_URL = 'https://esm.sh/typescript@5'
+
+const TS_GLOBAL = '__TJS_TS__'
+
+export interface BrowserFromTSOptions extends FromTSOptions {
+  /** Override the CDN URL the TypeScript compiler is lazy-loaded from. */
+  typescriptUrl?: string
+}
+
+let loading: Promise<void> | null = null
+
+/** Lazy-load the TypeScript compiler (once) onto `globalThis.__TJS_TS__`. */
+export function loadTypeScript(
+  url: string = DEFAULT_TYPESCRIPT_URL
+): Promise<void> {
+  if ((globalThis as any)[TS_GLOBAL]) return Promise.resolve()
+  if (!loading) {
+    loading = import(/* @vite-ignore */ /* webpackIgnore: true */ url).then(
+      (mod) => {
+        const ts = mod?.default ?? mod
+        if (!ts || typeof ts.createSourceFile !== 'function') {
+          loading = null
+          throw new Error(
+            `Loaded ${url} but it is not a usable TypeScript compiler ` +
+              `(no createSourceFile). Try a different typescriptUrl.`
+          )
+        }
+        ;(globalThis as any)[TS_GLOBAL] = ts
+      },
+      (e) => {
+        loading = null
+        throw e
+      }
+    )
+  }
+  return loading
+}
+
+/**
+ * Transpile TypeScript → TJS (or JS) in the browser. Lazy-loads the TypeScript
+ * compiler on first call, then runs the same `fromTS` logic as Node.
+ */
+export async function fromTS(
+  source: string,
+  options: BrowserFromTSOptions = {}
+): Promise<FromTSResult> {
+  const { typescriptUrl, ...rest } = options
+  await loadTypeScript(typescriptUrl)
+  // Imported after the compiler is set; from-ts's `typescript` import is aliased
+  // to the Proxy shim, which now forwards to the loaded compiler.
+  const { fromTS: nodeFromTS } = await import('./emitters/from-ts')
+  return nodeFromTS(source, rest)
+}
+
+export type { FromTSOptions, FromTSResult } from './emitters/from-ts'

package/src/lang/browser.ts

@@ -0,0 +1,13 @@
+/**
+ * Self-contained browser entry — the TJS/AJS transpiler with `acorn` and
+ * `tosijs-schema` bundled in (no external/bare imports). Build target
+ * `tjs-browser` (see `scripts/build.ts`) emits a single ESM file you can
+ * `import()` from any CDN with zero import-map / config:
+ *
+ *   const { tjs } = await import('https://cdn.jsdelivr.net/npm/tjs-lang/dist/tjs-browser.js')
+ *   const { code } = tjs("function greet(name: 'x'): '' { return 'hi' }")
+ *
+ * For TypeScript→TJS in the browser, use `tjs-lang/browser/from-ts` (which
+ * lazy-loads the TypeScript compiler from a CDN on demand).
+ */
+export * from './transpiler'

package/src/lang/emitters/from-ts.ts

@@ -1095,19 +1095,33 @@ function transformGenericInterfaceToGeneric(
   if (declarationAnnotation?.text) {
     parts.push(`declaration ${declarationAnnotation.text}`)
   } else {
-    // Auto-generate declaration block from interface members
+    // Auto-generate declaration block from interface members. Each member's
+    // type is converted to a TJS example via `typeToExample` (the same converter
+    // the non-generic interface path uses) rather than emitted as raw TS — so
+    // `path: string` → `path: ''`, `touch: () => void` → a FunctionPredicate
+    // example, and un-representable shapes (call-signature objects, etc.) degrade
+    // to a safe placeholder instead of producing TJS that won't re-parse.
+    // (The `@tjs declaration { … }` annotation path above is verbatim and
+    // unaffected — authors can still hand-write precise type signatures.)
     const declMembers: string[] = []
     for (const member of node.members) {
       if (ts.isPropertySignature(member) && member.name) {
         const propName = member.name.getText(sourceFile)
         const optional = member.questionToken ? '?' : ''
-        const typeText = member.type ? member.type.getText(sourceFile) : 'any'
-        declMembers.push(`${propName}${optional}: ${typeText}`)
+        const example = member.type
+          ? typeToExample(member.type, undefined, warnings)
+          : 'null'
+        declMembers.push(`${propName}${optional}: ${example}`)
       } else if (ts.isMethodSignature(member) && member.name) {
-        // Method: name(params): returnType
-        const methodText = member.getText(sourceFile).trim()
-        // Remove trailing semicolon if present
-        declMembers.push(methodText.replace(/;$/, ''))
+        // Method → a function example built from its return type (params are
+        // descriptive; the predicate above does the actual runtime check).
+        const propName = member.name.getText(sourceFile)
+        const ret = member.type
+          ? typeToExample(member.type, undefined, warnings)
+          : 'null'
+        declMembers.push(
+          `${propName}: FunctionPredicate('function', { returns: ${ret} })`
+        )
       }
     }
     if (declMembers.length > 0) {
@@ -1288,10 +1302,17 @@ function transformTypeAliasToType(
 
   const example = typeToExample(node.type, undefined, warnings)
 
-  // 'any' and 'undefined' — preserve original TS body for DTS round-tripping
+  // 'any' and 'undefined' — un-representable in TJS (intersections with
+  // `typeof`/index signatures, etc.). Degrade to an empty Type (validates as
+  // anything) and preserve the original TS body as a SINGLE-LINE comment so the
+  // DTS emitter can recover it. The collapse is essential: a multi-line type
+  // body would leave lines 2+ uncommented = raw TS leaking into the block =
+  // unparseable. (Representable shapes never reach here — they convert above.)
   if (example === 'any' || example === 'undefined') {
-    const originalType = node.type.getText(sourceFile).trim()
-    // Include the TS type body so the DTS emitter can recover it
+    const originalType = node.type
+      .getText(sourceFile)
+      .trim()
+      .replace(/\s+/g, ' ')
     return `Type ${typeName} {\n  // TS: ${originalType}\n}`
   }
 
@@ -1423,25 +1444,35 @@ function transformGenericTypeAliasToGeneric(
     const typeBody = node.type
 
     if (typeBody && ts.isTypeLiteralNode(typeBody)) {
-      // Object type literal: { item: T; count: number }
+      // Object type literal: { item: T; count: number }. Convert each member's
+      // type to a TJS example (degrades gracefully) rather than emitting raw TS.
       const declMembers: string[] = []
       for (const member of typeBody.members) {
         if (ts.isPropertySignature(member) && member.name) {
           const propName = member.name.getText(sourceFile)
           const optional = member.questionToken ? '?' : ''
-          const typeText = member.type ? member.type.getText(sourceFile) : 'any'
-          declMembers.push(`${propName}${optional}: ${typeText}`)
+          const example = member.type
+            ? typeToExample(member.type, undefined, warnings)
+            : 'null'
+          declMembers.push(`${propName}${optional}: ${example}`)
         } else if (ts.isMethodSignature(member) && member.name) {
-          declMembers.push(member.getText(sourceFile).trim().replace(/;$/, ''))
+          const propName = member.name.getText(sourceFile)
+          const ret = member.type
+            ? typeToExample(member.type, undefined, warnings)
+            : 'null'
+          declMembers.push(
+            `${propName}: FunctionPredicate('function', { returns: ${ret} })`
+          )
         }
       }
       if (declMembers.length > 0) {
         parts.push(`declaration {\n    ${declMembers.join('\n    ')}\n  }`)
       }
     } else if (typeBody) {
-      // Complex type (conditional, mapped, intersection, etc.)
-      // Pass through the TS type body verbatim
-      const typeText = typeBody.getText(sourceFile).trim()
+      // Complex type (conditional, mapped, intersection, …) — un-representable.
+      // Keep the TS body as a SINGLE-LINE comment (collapse newlines, else lines
+      // 2+ leak as raw TS and won't re-parse).
+      const typeText = typeBody.getText(sourceFile).trim().replace(/\s+/g, ' ')
       parts.push(`declaration {\n    // TS: ${typeText}\n  }`)
     }
   }

package/src/lang/from-ts.test.ts

@@ -312,3 +312,51 @@ describe('@tjs annotations', () => {
     })
   })
 })
+
+// Regression: TS→TJS must never emit TJS that won't re-parse. These real-world
+// shapes (from tosijs) used to leak raw TS into Type/Generic blocks — generic
+// interfaces emitted raw member types in `declaration {}`, and intersections /
+// complex types emitted MULTI-LINE `// TS:` comments whose lines 2+ leaked as
+// raw TS. fromTS now converts members via typeToExample and collapses
+// un-representable bodies to a single-line comment (graceful degradation).
+describe('TS→TJS round-trips (no raw-TS leak into TJS blocks)', () => {
+  const { tjs } = require('./index') as { tjs: (s: string) => { code: string } }
+  const roundTrips = (ts: string) => {
+    const emitted = fromTS(ts, { emitTJS: true }).code
+    expect(() => tjs(emitted)).not.toThrow() // emitted TJS must re-parse
+    return emitted
+  }
+
+  it('generic interface with complex members (arrow, generic arrow, call-sig)', () => {
+    const out = roundTrips(`export interface Acc<T = any> {
+      value: T
+      path: string
+      touch: () => void
+      bind: <E extends Element = Element>(el: E, b: any) => void
+      find: { (selector: (item: any) => any, value: any): any }
+    }`)
+    // members converted to examples, not raw TS
+    expect(out).toContain("path: ''")
+    expect(out).toContain('touch: FunctionPredicate')
+    expect(out).not.toMatch(/path: string\b/) // no raw type leak
+  })
+
+  it('intersection type alias (typeof / index signature) degrades, single-line', () => {
+    const out = roundTrips(`export type ProxyObj = Props<object> & {
+      [key: string]: ProxyObj | string | null
+    }`)
+    // un-representable → comment-only Type, collapsed to one line (no leak)
+    expect(out).toMatch(/\/\/ TS:.*&/)
+    expect(out).not.toMatch(/\n\s*\[key: string\]:/) // the body didn't leak raw
+  })
+
+  it('generic type alias with object body + arrow member', () => {
+    roundTrips(`export type Wrap<T> = { value: T; build: (x: T) => T }`)
+  })
+
+  it('plain type alias with arrow + union return still works', () => {
+    roundTrips(
+      `export type AnyFunction = (...args: any[]) => any | Promise<any>`
+    )
+  })
+})

package/src/lang/ts-cdn-shim.ts

@@ -0,0 +1,35 @@
+/**
+ * Build-time stand-in for the `typescript` module, used ONLY by the
+ * `tjs-browser-from-ts` bundle (via an esbuild `alias`). `from-ts.ts` does
+ * `import ts from 'typescript'` and accesses `ts.<x>` at call time; this Proxy
+ * forwards every access to the compiler that `browser-from-ts.ts` lazy-loads
+ * from a CDN and stashes on `globalThis.__TJS_TS__`.
+ *
+ * Because all of from-ts's `ts.<x>` uses are inside functions (run when `fromTS`
+ * is called, never at module load), the access is always deferred to after the
+ * compiler is loaded — so the swap needs no changes to `from-ts.ts`. tsc still
+ * typechecks `from-ts.ts` against the real `typescript` types; only the browser
+ * BUILD aliases the runtime to this shim.
+ */
+const TS_GLOBAL = '__TJS_TS__'
+
+function compiler(): any {
+  const ts = (globalThis as any)[TS_GLOBAL]
+  if (!ts) {
+    throw new Error(
+      'TypeScript not loaded. Use fromTS() from tjs-lang/browser/from-ts, ' +
+        'which lazy-loads the compiler before transpiling.'
+    )
+  }
+  return ts
+}
+
+const shim: any = new Proxy(
+  {},
+  {
+    get: (_t, prop) => compiler()[prop],
+    has: (_t, prop) => prop in compiler(),
+  }
+)
+
+export default shim