tjs-lang 0.5.1 → 0.5.2

package/demo/docs.json

@@ -67,9 +67,9 @@
     "type": "example",
     "group": "basics",
     "order": 1,
-    "code": "/*#\nThe classic first function in any language.\n\nDemonstrates:\n- Type annotations via examples (name: 'World')\n- Return type example (-> 'Hello, World') - tests the signature!\n- Inline tests with test blocks\n- Markdown documentation via /*# comments\n*/\ntest 'greet says hello' {\n  expect(greet('TJS')).toBe('Hello, TJS!')\n}\n\nfunction greet(name: 'World') -> 'Hello, World!' {\n  return `Hello, ${name}!`\n}",
+    "code": "/*#\n## Types by Example\n\nIn TJS, the example value after `:` IS the type:\n\n| Syntax | Type |\n|--------|------|\n| `name: 'Alice'` | string (required) |\n| `count: 42` | integer |\n| `rate: 3.14` | number (float) |\n| `index: +0` | non-negative integer |\n| `name = 'default'` | string (optional, defaults to 'default') |\n| `data: { x: 0, y: 0 }` | object with shape |\n*/\n\nfunction greet(name: 'World') -> 'Hello, World!' {\n  return `Hello, ${name}!`\n}\n\n// Numeric type narrowing — all valid JS syntax\nfunction clampIndex(index: +0, max: +0) -> +0 {\n  return Math.min(index, max)\n}\n\nfunction mix(a: 0.0, b: 0.0, t: 0.0) -> 0.0 {\n  return a + (b - a) * t\n}\n\ntest 'greet says hello' {\n  expect(greet('TJS')).toBe('Hello, TJS!')\n}\n\ntest 'type errors are values, not exceptions' {\n  const err = greet(42)\n  expect(err instanceof Error).toBe(true)\n}\n\ntest 'numeric types are precise' {\n  expect(clampIndex(5, 10)).toBe(5)\n  // negative fails non-negative integer check\n  expect(clampIndex(-1, 10) instanceof Error).toBe(true)\n  // float fails integer check\n  expect(clampIndex(3.5, 10) instanceof Error).toBe(true)\n}\n\ntest 'floats accept any number' {\n  expect(mix(0, 100, 0.5)).toBe(50)\n}",
     "language": "tjs",
-    "description": "Simple typed greeting function with docs and tests"
+    "description": "Types-by-example: the value IS the type annotation"
   },
   {
     "title": "Required vs Optional",
@@ -173,7 +173,7 @@
     "type": "example",
     "group": "featured",
     "order": 0,
-    "code": "// ═══════════════════════════════════════════════════════════\n// 1. SAFETY DIRECTIVE & TJS MODES\n// These must appear before any other code.\n// ═══════════════════════════════════════════════════════════\n\nsafety inputs\n\nTjsEquals\nTjsClass\n\n/*#\n# TJS Grammar Reference\n\nA runnable reference for TJS syntax. Each section demonstrates a\nfeature with a test proving it works.\n\n## Quick Index\n| Feature | Section |\n|---------|---------|\n| Safety & modes | `safety`, `TjsEquals`, `TjsClass` |\n| Parameters | Colon `:`, optional `=`, destructured `{}` |\n| Numeric narrowing | `42` int, `3.14` float, `+0` non-negative |\n| Return types | `->`, `-?`, `-!` |\n| Safety markers | `(! ...)` unsafe, `(? ...)` safe |\n| Type/Generic/Enum/Union | See above (requires full runtime) |\n| Bare assignments | `Uppercase = ...` |\n| Classes | Callable without `new` |\n| Polymorphic functions | Same name, different signatures |\n| Polymorphic constructors | Multiple `constructor()` |\n| Local extensions | `extend String { ... }` |\n| Equality | `==` structural, `===` identity, `Is`/`IsNot` |\n| Try without catch | Monadic error conversion |\n| Inline tests | Test blocks |\n| TDoc comments | Slash-star-hash markdown blocks |\n*/\n\n// ═══════════════════════════════════════════════════════════\n// 2. PARAMETER SYNTAX\n// ═══════════════════════════════════════════════════════════\n\n/*#\n## Parameters\n\nColon `:` = required (example value infers type).\nEquals `=` = optional (default value).\nQuestion mark `?:` = optional (TS-style).\n*/\n\n// Required params (colon shorthand)\nfunction greet(name: 'Alice') -> 'Hello, Alice' {\n  return 'Hello, ' + name\n}\n\n// Optional params (equals = default)\nfunction greetOpt(name = 'World') -> 'Hello, World' {\n  return 'Hello, ' + name\n}\n\n// Destructured object params (colon = required, equals = optional)\nfunction createUser({ name: 'Anon', role = 'user' }) -> { name: '', role: '' } {\n  return { name, role }\n}\n\n// Numeric type narrowing: 42 = integer, 3.14 = float, +0 = non-negative int\nfunction calc(count: 42, rate: 3.14, index: +0) -> 0.0 {\n  return (count + index) * rate\n}\n\ntest 'parameter syntax' {\n  expect(greet('Bob')).toBe('Hello, Bob')\n  expect(greetOpt()).toBe('Hello, World')\n  expect(createUser({ name: 'Eve' })).toEqual({ name: 'Eve', role: 'user' })\n  expect(calc(10, 1.5, 2)).toBe(18)\n}\n\n// ═══════════════════════════════════════════════════════════\n// 3. RETURN TYPES\n// ═══════════════════════════════════════════════════════════\n\n/*#\n## Return Types\n\n`->` signature test at transpile time.\n`-?` signature test + runtime output validation.\n`-!` skip signature test entirely.\n*/\n\n// -> : transpile-time check (double(5) must equal 10)\nfunction double(x: 5) -> 10 {\n  return x * 2\n}\n\n// -! : skip test (useful when return shape varies)\nfunction safeDivide(a: 10, b: 2) -! 5 {\n  if (b === 0) return { error: 'div by zero' }\n  return a / b\n}\n\ntest 'return types' {\n  expect(double(7)).toBe(14)\n  expect(safeDivide(10, 0)).toEqual({ error: 'div by zero' })\n}\n\n// ═══════════════════════════════════════════════════════════\n// 4. SAFETY MARKERS\n// ═══════════════════════════════════════════════════════════\n\n/*#\n## Safety Markers\n\n`!` = unsafe (skip input validation). Fast path for trusted callers.\n`?` = safe (force validation even inside `unsafe` blocks).\n*/\n\nfunction fastAdd(! a: 0, b: 0) -> 0 {\n  return a + b\n}\n\nfunction safeAdd(? a: 0, b: 0) -> 0 {\n  return a + b\n}\n\ntest 'safety markers' {\n  expect(fastAdd(3, 4)).toBe(7)\n  expect(safeAdd(3, 4)).toBe(7)\n}\n\n// ═══════════════════════════════════════════════════════════\n// 5. BARE ASSIGNMENTS\n// ═══════════════════════════════════════════════════════════\n\n/*#\n## Bare Assignments\n\nUppercase identifiers auto-get `const`.\n*/\n\nGreeting = 'Hello'\nMaxRetries = 3\n\ntest 'bare assignments' {\n  expect(Greeting).toBe('Hello')\n  expect(MaxRetries).toBe(3)\n}\n\n// ═══════════════════════════════════════════════════════════\n// 7. CLASSES (callable without new)\n// ═══════════════════════════════════════════════════════════\n\n/*#\n## Classes\n\nWith `TjsClass` enabled, classes are callable without `new`.\n*/\n\nclass Point {\n  constructor(x: 0.0, y: 0.0) {\n    this.x = x\n    this.y = y\n  }\n\n  magnitude() {\n    return Math.sqrt(this.x * this.x + this.y * this.y)\n  }\n}\n\ntest 'classes callable without new' {\n  const p = Point(3, 4)\n  expect(p instanceof Point).toBe(true)\n  expect(p.magnitude()).toBe(5)\n}\n\n// ═══════════════════════════════════════════════════════════\n// 8. POLYMORPHIC FUNCTIONS\n// ═══════════════════════════════════════════════════════════\n\n/*#\n## Polymorphic Functions\n\nSame name, different signatures. Dispatched by arity/type.\nSee the **Polymorphic Functions** example for more.\n*/\n\nfunction describe(value: 0) {\n  return 'number: ' + value\n}\n\nfunction describe(first: '', last: '') {\n  return first + ' ' + last\n}\n\ntest 'polymorphic dispatch by arity' {\n  expect(describe(42)).toBe('number: 42')\n  expect(describe('Jane', 'Doe')).toBe('Jane Doe')\n}\n\n// ═══════════════════════════════════════════════════════════\n// 9. POLYMORPHIC CONSTRUCTORS\n// ═══════════════════════════════════════════════════════════\n\n/*#\n## Polymorphic Constructors\n\nMultiple `constructor()` declarations in a class.\nSee the **Polymorphic Constructors** example for more.\n*/\n\nclass Vec2 {\n  constructor(x: 0.0, y: 0.0) {\n    this.x = x\n    this.y = y\n  }\n\n  constructor(obj: { x: 0.0, y: 0.0 }) {\n    this.x = obj.x\n    this.y = obj.y\n  }\n}\n\ntest 'polymorphic constructors' {\n  const a = Vec2(1, 2)\n  const b = Vec2({ x: 1, y: 2 })\n  expect(a.x).toBe(b.x)\n  expect(a.y).toBe(b.y)\n}\n\n// ═══════════════════════════════════════════════════════════\n// 10. LOCAL EXTENSIONS\n// ═══════════════════════════════════════════════════════════\n\n/*#\n## Local Extensions\n\nAdd methods to built-in types without prototype pollution.\nRewritten to `.call()` at transpile time for known types.\nSee the **Local Extensions** example for a runnable demo.\n\n    extend String {\n      capitalize() { return this[0].toUpperCase() + this.slice(1) }\n    }\n\n    extend Array {\n      last() { return this[this.length - 1] }\n    }\n\n    'hello'.capitalize()  // 'Hello'\n    [1, 2, 3].last()      // 3\n*/\n\n// ═══════════════════════════════════════════════════════════\n// 11. EQUALITY OPERATORS\n// ═══════════════════════════════════════════════════════════\n\n/*#\n## Equality\n\nWith `TjsEquals` enabled (at the top of this file):\n- `==` / `!=` use structural comparison (deep value equality)\n- `===` / `!==` are identity checks (same reference)\n- `Is` / `IsNot` are explicit structural operators (any mode)\n\n    const a = { x: 1, y: [2, 3] }\n    const b = { x: 1, y: [2, 3] }\n    a == b       // true  (structural: same shape)\n    a === b      // false (identity: different objects)\n    a Is b       // true  (explicit structural)\n    a IsNot b    // false\n*/\n\n// ═══════════════════════════════════════════════════════════\n// 12. TRY WITHOUT CATCH\n// ═══════════════════════════════════════════════════════════\n\n/*#\n## Try Without Catch\n\nA bare `try` block auto-converts exceptions to monadic errors.\n*/\n\nfunction parseJSON(s: '{\"a\":1}') -! { a: 1 } {\n  try {\n    return JSON.parse(s)\n  }\n}\n\ntest 'try without catch' {\n  expect(parseJSON('{\"ok\":true}')).toEqual({ ok: true })\n  const bad = parseJSON('not json')\n  expect(bad.$error).toBe(true)\n}\n\n// ═══════════════════════════════════════════════════════════\n// 13. INLINE TESTS\n// ═══════════════════════════════════════════════════════════\n\n/*#\n## Inline Tests\n\nTest blocks run at transpile time and are stripped from\noutput. They have full access to the module scope, so you\ncan test private functions without exporting them.\n*/\n\nfunction _private(x: 0) -> 0 {\n  return x * x\n}\n\ntest 'inline tests can reach private functions' {\n  expect(_private(5)).toBe(25)\n}\n\n// ═══════════════════════════════════════════════════════════\n// 14. MODULE EXPORTS\n// ═══════════════════════════════════════════════════════════\n\n/*#\n## Module Exports\n\nStandard ES module syntax works. Functions and values\ncan be exported for use by other modules.\n*/\n\nexport function publicHelper(x: 0) -> 0 {\n  return x + 1\n}\n\n// ═══════════════════════════════════════════════════════════\n// 15. TDOC COMMENTS\n// ═══════════════════════════════════════════════════════════\n\n/*#\n## TDoc Comments\n\nThese comment blocks (opened with slash-star-hash) contain\nmarkdown that becomes rich documentation in the playground\nand API docs. Every such block you've seen above is a TDoc.\n*/\n\n// ═══════════════════════════════════════════════════════════\n// OUTPUT\n// ═══════════════════════════════════════════════════════════\n\nconsole.log('TJS Grammar Reference — all tests passed!')\nconsole.log('Features demonstrated:', [\n  'safety directive', 'TJS modes', 'colon params', 'optional params',\n  'destructured params', 'numeric narrowing',\n  'return types (-> -? -!)', 'safety markers (! ?)',\n  'Type', 'Generic', 'Enum', 'Union', 'bare assignments',\n  'classes', 'polymorphic functions', 'polymorphic constructors',\n  'local extensions', 'structural equality', 'Is/IsNot',\n  'try without catch', 'inline tests', 'module exports', 'TDoc'\n].join(', '))",
+    "code": "// ═══════════════════════════════════════════════════════════\n// 1. SAFETY DIRECTIVE & TJS MODES\n// These must appear before any other code.\n// ═══════════════════════════════════════════════════════════\n\nsafety inputs\n\nTjsEquals\nTjsClass\n\n/*#\n# TJS Grammar Reference\n\nA runnable reference for TJS syntax. Each section demonstrates a\nfeature with a test proving it works.\n\n## Quick Index\n| Feature | Section |\n|---------|---------|\n| Safety & modes | `safety`, `TjsEquals`, `TjsClass` |\n| Parameters | Colon `:`, optional `=`, destructured `{}` |\n| Numeric narrowing | `42` int, `3.14` float, `+0` non-negative |\n| Return types | `->`, `-?`, `-!` |\n| Safety markers | `(! ...)` unsafe, `(? ...)` safe |\n| Type/Generic/Enum/Union | See above (requires full runtime) |\n| Bare assignments | `Uppercase = ...` |\n| Classes | Callable without `new` |\n| Polymorphic functions | Same name, different signatures |\n| Polymorphic constructors | Multiple `constructor()` |\n| Local extensions | `extend String { ... }` |\n| Equality | `==` structural, `===` identity, `Is`/`IsNot` |\n| Try without catch | Monadic error conversion |\n| Inline tests | Test blocks |\n| TDoc comments | Slash-star-hash markdown blocks |\n*/\n\n// ═══════════════════════════════════════════════════════════\n// 2. PARAMETER SYNTAX\n// ═══════════════════════════════════════════════════════════\n\n/*#\n## Parameters\n\nColon `:` = required (example value infers type).\nEquals `=` = optional (default value).\nQuestion mark `?:` = optional (TS-style).\n*/\n\n// Required params (colon shorthand)\nfunction greet(name: 'Alice') -> 'Hello, Alice' {\n  return 'Hello, ' + name\n}\n\n// Optional params (equals = default)\nfunction greetOpt(name = 'World') -> 'Hello, World' {\n  return 'Hello, ' + name\n}\n\n// Destructured object params (colon = required, equals = optional)\nfunction createUser({ name: 'Anon', role = 'user' }) -> { name: '', role: '' } {\n  return { name, role }\n}\n\n// Numeric type narrowing: 42 = integer, 3.14 = float, +0 = non-negative int\nfunction calc(count: 42, rate: 3.14, index: +0) -> 0.0 {\n  return (count + index) * rate\n}\n\ntest 'parameter syntax' {\n  expect(greet('Bob')).toBe('Hello, Bob')\n  expect(greetOpt()).toBe('Hello, World')\n  expect(createUser({ name: 'Eve' })).toEqual({ name: 'Eve', role: 'user' })\n  expect(calc(10, 1.5, 2)).toBe(18)\n}\n\n// ═══════════════════════════════════════════════════════════\n// 3. RETURN TYPES\n// ═══════════════════════════════════════════════════════════\n\n/*#\n## Return Types\n\n`->` signature test at transpile time.\n`-?` signature test + runtime output validation.\n`-!` skip signature test entirely.\n*/\n\n// -> : transpile-time check (double(5) must equal 10)\nfunction double(x: 5) -> 10 {\n  return x * 2\n}\n\n// -! : skip test (useful when return shape varies)\nfunction safeDivide(a: 10, b: 2) -! 5 {\n  if (b === 0) return { error: 'div by zero' }\n  return a / b\n}\n\ntest 'return types' {\n  expect(double(7)).toBe(14)\n  expect(safeDivide(10, 0)).toEqual({ error: 'div by zero' })\n}\n\n// ═══════════════════════════════════════════════════════════\n// 4. SAFETY MARKERS\n// ═══════════════════════════════════════════════════════════\n\n/*#\n## Safety Markers\n\n`!` = unsafe (skip input validation). Fast path for trusted callers.\n`?` = safe (force validation even inside `unsafe` blocks).\n*/\n\nfunction fastAdd(! a: 0, b: 0) -> 0 {\n  return a + b\n}\n\nfunction safeAdd(? a: 0, b: 0) -> 0 {\n  return a + b\n}\n\ntest 'safety markers' {\n  expect(fastAdd(3, 4)).toBe(7)\n  expect(safeAdd(3, 4)).toBe(7)\n}\n\n// ═══════════════════════════════════════════════════════════\n// 5. BARE ASSIGNMENTS\n// ═══════════════════════════════════════════════════════════\n\n/*#\n## Bare Assignments\n\nUppercase identifiers auto-get `const`.\n*/\n\nGreeting = 'Hello'\nMaxRetries = 3\n\ntest 'bare assignments' {\n  expect(Greeting).toBe('Hello')\n  expect(MaxRetries).toBe(3)\n}\n\n// ═══════════════════════════════════════════════════════════\n// 7. CLASSES (callable without new)\n// ═══════════════════════════════════════════════════════════\n\n/*#\n## Classes\n\nWith `TjsClass` enabled, classes are callable without `new`.\n*/\n\nclass Point {\n  constructor(x: 0.0, y: 0.0) {\n    this.x = x\n    this.y = y\n  }\n\n  magnitude() {\n    return Math.sqrt(this.x * this.x + this.y * this.y)\n  }\n}\n\ntest 'classes callable without new' {\n  const p = Point(3, 4)\n  expect(p instanceof Point).toBe(true)\n  expect(p.magnitude()).toBe(5)\n}\n\n// ═══════════════════════════════════════════════════════════\n// 8. POLYMORPHIC FUNCTIONS\n// ═══════════════════════════════════════════════════════════\n\n/*#\n## Polymorphic Functions\n\nSame name, different signatures. Dispatched by arity/type.\nSee the **Polymorphic Functions** example for more.\n*/\n\nfunction describe(value: 0) {\n  return 'number: ' + value\n}\n\nfunction describe(first: '', last: '') {\n  return first + ' ' + last\n}\n\ntest 'polymorphic dispatch by arity' {\n  expect(describe(42)).toBe('number: 42')\n  expect(describe('Jane', 'Doe')).toBe('Jane Doe')\n}\n\n// ═══════════════════════════════════════════════════════════\n// 9. POLYMORPHIC CONSTRUCTORS\n// ═══════════════════════════════════════════════════════════\n\n/*#\n## Polymorphic Constructors\n\nMultiple `constructor()` declarations in a class.\nSee the **Polymorphic Constructors** example for more.\n*/\n\nclass Vec2 {\n  constructor(x: 0.0, y: 0.0) {\n    this.x = x\n    this.y = y\n  }\n\n  constructor(obj: { x: 0.0, y: 0.0 }) {\n    this.x = obj.x\n    this.y = obj.y\n  }\n}\n\ntest 'polymorphic constructors' {\n  const a = Vec2(1, 2)\n  const b = Vec2({ x: 1, y: 2 })\n  expect(a.x).toBe(b.x)\n  expect(a.y).toBe(b.y)\n}\n\n// ═══════════════════════════════════════════════════════════\n// 10. LOCAL EXTENSIONS\n// ═══════════════════════════════════════════════════════════\n\n/*#\n## Local Extensions\n\nAdd methods to built-in types without prototype pollution.\nRewritten to `.call()` at transpile time for known types.\nSee the **Local Extensions** example for a runnable demo.\n\n    extend String {\n      capitalize() { return this[0].toUpperCase() + this.slice(1) }\n    }\n\n    extend Array {\n      last() { return this[this.length - 1] }\n    }\n\n    'hello'.capitalize()  // 'Hello'\n    [1, 2, 3].last()      // 3\n*/\n\n// ═══════════════════════════════════════════════════════════\n// 11. EQUALITY OPERATORS\n// ═══════════════════════════════════════════════════════════\n\n/*#\n## Equality\n\nWith `TjsEquals` enabled (at the top of this file):\n- `==` / `!=` use structural comparison (deep value equality)\n- `===` / `!==` are identity checks (same reference)\n- `Is` / `IsNot` are explicit structural operators (any mode)\n\n    const a = { x: 1, y: [2, 3] }\n    const b = { x: 1, y: [2, 3] }\n    a == b       // true  (structural: same shape)\n    a === b      // false (identity: different objects)\n    a Is b       // true  (explicit structural)\n    a IsNot b    // false\n*/\n\n// ═══════════════════════════════════════════════════════════\n// 12. TRY WITHOUT CATCH\n// ═══════════════════════════════════════════════════════════\n\n/*#\n## Try Without Catch\n\nA bare `try` block auto-converts exceptions to monadic errors.\n*/\n\nfunction parseJSON(s: '{\"a\":1}') -! { a: 1 } {\n  try {\n    return JSON.parse(s)\n  }\n}\n\ntest 'try without catch' {\n  expect(parseJSON('{\"ok\":true}')).toEqual({ ok: true })\n  const bad = parseJSON('not json')\n  expect(bad instanceof Error).toBe(true)\n}\n\n// ═══════════════════════════════════════════════════════════\n// 13. INLINE TESTS\n// ═══════════════════════════════════════════════════════════\n\n/*#\n## Inline Tests\n\nTest blocks run at transpile time and are stripped from\noutput. They have full access to the module scope, so you\ncan test private functions without exporting them.\n*/\n\nfunction _private(x: 0) -> 0 {\n  return x * x\n}\n\ntest 'inline tests can reach private functions' {\n  expect(_private(5)).toBe(25)\n}\n\n// ═══════════════════════════════════════════════════════════\n// 14. MODULE EXPORTS\n// ═══════════════════════════════════════════════════════════\n\n/*#\n## Module Exports\n\nStandard ES module syntax works. Functions and values\ncan be exported for use by other modules.\n*/\n\nexport function publicHelper(x: 0) -> 0 {\n  return x + 1\n}\n\n// ═══════════════════════════════════════════════════════════\n// 15. TDOC COMMENTS\n// ═══════════════════════════════════════════════════════════\n\n/*#\n## TDoc Comments\n\nThese comment blocks (opened with slash-star-hash) contain\nmarkdown that becomes rich documentation in the playground\nand API docs. Every such block you've seen above is a TDoc.\n*/\n\n// ═══════════════════════════════════════════════════════════\n// OUTPUT\n// ═══════════════════════════════════════════════════════════\n\nconsole.log('TJS Grammar Reference — all tests passed!')\nconsole.log('Features demonstrated:', [\n  'safety directive', 'TJS modes', 'colon params', 'optional params',\n  'destructured params', 'numeric narrowing',\n  'return types (-> -? -!)', 'safety markers (! ?)',\n  'Type', 'Generic', 'Enum', 'Union', 'bare assignments',\n  'classes', 'polymorphic functions', 'polymorphic constructors',\n  'local extensions', 'structural equality', 'Is/IsNot',\n  'try without catch', 'inline tests', 'module exports', 'TDoc'\n].join(', '))",
     "language": "tjs",
     "description": "Comprehensive reference covering all major TJS syntax features. **Type declarations** (require full `tjs-lang` runtime — shown here for reference): Type Name = 'Alice' Type Age 'a non-negative age' { example: 25 predicate(x) { return typeof x === 'number' && x >= 0 } } Generic Pair<A, B> { description: 'a pair of values' predicate(obj, A, B) { ... } } Enum Direction 'cardinal direction' { North, East, South, West } Enum Color 'CSS color' { Red = 'red', Green = 'green', Blue = 'blue' } Union Status 'task status' 'pending' | 'active' | 'done' All other features are exercised in the runnable code below:"
   },
@@ -209,7 +209,7 @@
     "type": "example",
     "group": "fullstack",
     "order": 13,
-    "code": "/**\n * # Client Application\n *\n * A frontend that calls the User Service.\n *\n * **First:** Run the \"User Service\" example and save it as \"user-service\"\n * **Then:** Run this client to see full-stack in action\n *\n * This demonstrates:\n * - Importing local TJS modules\n * - Type-safe service calls\n * - Error handling\n */\n\n// Import from local module (saved in playground)\nimport { createUser, getUser, listUsers, searchUsers } from 'user-service'\n\n// Helper to display results\nfunction display(label: '', data: {}) {\n  console.log(`\\\\n\\${label}:`)\n  console.log(JSON.stringify(data, null, 2))\n}\n\n// Main app\nasync function main() {\n  console.log('=== Client App ===')\n  console.log('Connecting to user-service...\\\\n')\n\n  // Create some users\n  const user1 = createUser({ name: 'Dave', email: 'dave@startup.io' })\n  display('Created user', user1)\n\n  const user2 = createUser({ name: 'Eve', email: 'eve@startup.io' })\n  display('Created user', user2)\n\n  // Fetch a user\n  const fetched = getUser({ id: user1.id })\n  display('Fetched user', fetched)\n\n  // List all\n  const all = listUsers({ limit: 100, offset: 0 })\n  display('All users', all)\n\n  // Search\n  const results = searchUsers({ query: 'eve' })\n  display('Search results for \"eve\"', results)\n\n  // Type error handling\n  console.log('\\\\n--- Type Validation Demo ---')\n  const badResult = createUser({ name: 999 })\n  if (badResult.$error) {\n    console.log('Caught type error:', badResult.message)\n  }\n\n  console.log('\\\\n=== Full-Stack Demo Complete ===')\n  console.log('Everything ran in the browser. No server. No build step.')\n}\n\nmain()",
+    "code": "/**\n * # Client Application\n *\n * A frontend that calls the User Service.\n *\n * **First:** Run the \"User Service\" example and save it as \"user-service\"\n * **Then:** Run this client to see full-stack in action\n *\n * This demonstrates:\n * - Importing local TJS modules\n * - Type-safe service calls\n * - Error handling\n */\n\n// Import from local module (saved in playground)\nimport { createUser, getUser, listUsers, searchUsers } from 'user-service'\n\n// Helper to display results\nfunction display(label: '', data: {}) {\n  console.log(`\\\\n\\${label}:`)\n  console.log(JSON.stringify(data, null, 2))\n}\n\n// Main app\nasync function main() {\n  console.log('=== Client App ===')\n  console.log('Connecting to user-service...\\\\n')\n\n  // Create some users\n  const user1 = createUser({ name: 'Dave', email: 'dave@startup.io' })\n  display('Created user', user1)\n\n  const user2 = createUser({ name: 'Eve', email: 'eve@startup.io' })\n  display('Created user', user2)\n\n  // Fetch a user\n  const fetched = getUser({ id: user1.id })\n  display('Fetched user', fetched)\n\n  // List all\n  const all = listUsers({ limit: 100, offset: 0 })\n  display('All users', all)\n\n  // Search\n  const results = searchUsers({ query: 'eve' })\n  display('Search results for \"eve\"', results)\n\n  // Type error handling\n  console.log('\\\\n--- Type Validation Demo ---')\n  const badResult = createUser({ name: 999 })\n  if (badResult instanceof Error) {\n    console.log('Caught type error:', badResult.message)\n  }\n\n  console.log('\\\\n=== Full-Stack Demo Complete ===')\n  console.log('Everything ran in the browser. No server. No build step.')\n}\n\nmain()",
     "language": "tjs",
     "description": "Frontend that calls the User Service - run after saving user-service!"
   },
@@ -257,9 +257,9 @@
     "type": "example",
     "group": "patterns",
     "order": 7,
-    "code": "/*#\n## Monadic Error Handling\n\nTJS uses the Result pattern — errors are values, not exceptions.\nThis makes error handling explicit and type-safe.\n*/\ntest 'divide handles zero' {\n  const result = divide(10, 0)\n  expect(result.error).toBe('Division by zero')\n}\n\ntest 'divide works normally' {\n  const result = divide(10, 2)\n  expect(result.value).toBe(5)\n}\n\nfunction divide(a: 10, b: 2) -> { value: 0, error = '' } {\n  if (b === 0) {\n    return { value: NaN, error: 'Division by zero' }\n  }\n  return { value: a / b }\n}\n\nfunction safeParse(json: '{\"x\":1}') -! { data: null, error = '' } {\n  try {\n    return { data: JSON.parse(json) }\n  } catch (e) {\n    return { data: null, error: e.message }\n  }\n}\n\n// Usage — errors are values you can inspect\nconst result = divide(10, 0)\nif (!result.error) {\n  console.log('Result:', result.value)\n} else {\n  console.log('Error:', result.error)\n}",
+    "code": "/*#\n## Monadic Error Propagation\n\nType errors are values (MonadicError), not exceptions. They propagate\nautomatically through function chains — if any function receives an\nerror as input, it short-circuits and returns the error immediately.\n\nNo try/catch needed. No manual error checking between calls.\n*/\n\n// --- Error propagation through a pipeline ---\n\nfunction validate(name: '') -> '' {\n  return name.trim()\n}\n\nfunction greet(name: '') -> '' {\n  return `Hello, ${name}!`\n}\n\nfunction shout(text: '') -> '' {\n  return text.toUpperCase()\n}\n\ntest 'valid input flows through the pipeline' {\n  // Each function's output feeds the next function's input\n  const result = shout(greet(validate('alice')))\n  expect(result).toBe('HELLO, ALICE!')\n}\n\ntest 'type error propagates through the entire chain' {\n  // validate(42) returns a MonadicError (42 is not a string)\n  // greet() receives the error, short-circuits, returns it\n  // shout() receives the error, short-circuits, returns it\n  const result = shout(greet(validate(42)))\n  expect(result instanceof Error).toBe(true)\n  expect(result.message.includes('string')).toBe(true)\n}\n\ntest 'error identity is preserved (same object, not a copy)' {\n  const err = validate(42)\n  expect(greet(err)).toBe(err)\n  expect(shout(err)).toBe(err)\n}\n\n// --- Result pattern for domain errors ---\n\nfunction divide(a: 10, b: 2) -> { value: 0, error = '' } {\n  if (b === 0) {\n    return { value: NaN, error: 'Division by zero' }\n  }\n  return { value: a / b }\n}\n\ntest 'divide handles zero' {\n  const result = divide(10, 0)\n  expect(result.error).toBe('Division by zero')\n}\n\ntest 'divide works normally' {\n  const result = divide(10, 2)\n  expect(result.value).toBe(5)\n}\n\n// Errors propagate when passed as arguments to TJS functions.\n// If you use a potentially-error value in a JS expression (e.g. result.length),\n// check it first: if (result instanceof Error) return result\n// In debug mode, errors include a callStack showing the full call chain.",
     "language": "tjs",
-    "description": "Type-safe error handling patterns"
+    "description": "Monadic error propagation and type-safe error patterns"
   },
   {
     "title": "Schema Validation",
@@ -269,9 +269,9 @@
     "type": "example",
     "group": "patterns",
     "order": 8,
-    "code": "// TJS integrates with Schema for validation\nimport { Schema } from 'tosijs-schema'\n\n// Define a schema\nconst UserSchema = Schema({\n  name: 'anonymous',\n  email: 'user@example.com',\n  age: 0\n})\n\n// Validate data\nfunction validateUser(data: { name: '', email: '', age: 0 }) -> { valid: true, errors: [''] } {\n  const errors = []\n\n  if (!UserSchema.validate(data)) {\n    errors.push('Invalid user structure')\n  }\n\n  return {\n    valid: errors.length === 0,\n    errors\n  }\n}\n\nvalidateUser({ name: 'Alice', email: 'alice@test.com', age: 30 })",
+    "code": "/*#\n## Runtime Types\n\nEvery TJS function carries `__tjs` metadata with full type information.\nThis enables runtime validation, auto-generated docs, and introspection\n— all from the same type annotations you already write.\n*/\n\nfunction createUser(\n  name: 'anonymous',\n  email: 'user@example.com',\n  age: +0\n) -> { name: '', email: '', age: 0 } {\n  return { name, email, age }\n}\n\nfunction transfer(\n  from: '',\n  to: '',\n  amount: 0.0\n) -> { from: '', to: '', amount: 0.0 } {\n  return { from, to, amount }\n}\n\ntest 'functions validate at runtime' {\n  const user = createUser('Alice', 'alice@test.com', 30)\n  expect(user.name).toBe('Alice')\n\n  // Wrong type — returns error, no exception\n  const err = createUser('Alice', 'alice@test.com', -1)\n  expect(err instanceof Error).toBe(true)\n}\n\ntest 'metadata is introspectable' {\n  const meta = createUser.__tjs\n  expect(meta.params.name.type.kind).toBe('string')\n  expect(meta.params.age.type.kind).toBe('non-negative-integer')\n  expect(meta.returns.type.kind).toBe('object')\n}\n\n// Inspect live metadata\nconsole.log('createUser params:', createUser.__tjs.params)\nconsole.log('transfer params:', transfer.__tjs.params)\nconsole.log('transfer returns:', transfer.__tjs.returns)",
     "language": "tjs",
-    "description": "Using Schema for runtime type checking"
+    "description": "Types persist into runtime — inspect, validate, and document at zero extra cost"
   },
   {
     "title": "Date Formatting (with import)",

package/demo/src/service-host.ts

@@ -147,11 +147,11 @@ export class ServiceHost {
       // Call with TJS validation (built into the transpiled code)
       const result = fn(args)
 
-      // Check for monadic error
-      if (result && result.$error) {
+      // Check for monadic error (MonadicError extends Error)
+      if (result instanceof Error) {
         return {
           success: false,
-          error: { message: result.message, path: result.path },
+          error: { message: result.message, path: (result as any).path },
           fuel: 1, // minimal fuel for failed validation
           duration: performance.now() - start,
         }

package/demo/src/ts-examples.ts

@@ -163,8 +163,9 @@ console.log('10 / 0 =', divide(10, 0))
 const badResult = divide('ten' as any, 2)
 console.log('divide("ten", 2) =', badResult)
 
-if (badResult && badResult.$error) {
-  console.log('  ^ This is a validation error, not a crash!')
+if (badResult instanceof Error) {
+  console.log('  ^ This is a MonadicError, not a crash!')
+  console.log('  message:', badResult.message)
 }
 `,
   },

package/demo/src/ts-playground.ts

@@ -468,7 +468,7 @@ export class TSPlayground extends Component<TSPlaygroundParts> {
 
   run = async () => {
     this.clearConsole()
-    this.transpile()
+    await this.transpile()
 
     if (!this.lastJsCode) {
       this.log('Cannot run - transpilation failed')
@@ -548,7 +548,7 @@ export class TSPlayground extends Component<TSPlaygroundParts> {
   }
 
   // Public method to set source code (auto-runs when examples are loaded)
-  setSource(code: string, exampleName?: string) {
+  async setSource(code: string, exampleName?: string) {
     // Save current edits before switching
     if (this.currentExampleName) {
       this.editorCache.set(this.currentExampleName, this.parts.tsEditor.value)
@@ -565,9 +565,9 @@ export class TSPlayground extends Component<TSPlaygroundParts> {
     // Update revert button visibility
     this.updateRevertButton()
 
-    this.transpile()
+    await this.transpile()
     // Auto-run when source is loaded externally (e.g., from example selection)
-    this.run()
+    await this.run()
   }
 
   // Revert to the original example code

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tjs-lang",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "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",

package/src/lang/codegen.test.ts

@@ -1602,6 +1602,211 @@ function test(x: 0) -! 0 {
     })
   })
 
+  describe('stack management', () => {
+    it('stack is empty after successful calls', () => {
+      const { configure, resetRuntime } = require('./runtime')
+      resetRuntime()
+      configure({ debug: true })
+
+      try {
+        const { code } = tjs(`
+function add(a: 0, b: 0) -! 0 {
+  return a + b
+}
+`)
+        const add = new Function(code + '; return add')()
+
+        add(1, 2)
+        add(3, 4)
+        add(5, 6)
+
+        // Stack must be empty — no stale entries from successful calls
+        expect(globalThis.__tjs.getStack()).toEqual([])
+      } finally {
+        resetRuntime()
+      }
+    })
+
+    it('stack is clean after error propagates back up', () => {
+      const { configure, resetRuntime } = require('./runtime')
+      resetRuntime()
+      configure({ debug: true })
+
+      try {
+        const { code } = tjs(`/* tjs <- src/app.ts */
+/* line 1 */
+function outer(x: 0) -! 0 {
+  return inner(x)
+}
+/* line 5 */
+function inner(x: '') -! '' {
+  return x.toUpperCase()
+}
+`)
+        const fns = new Function(code + '; return { outer, inner }')()
+        const err = fns.outer(42)
+
+        expect(err).toBeInstanceOf(MonadicError)
+        // Stack must be empty after error has propagated back
+        expect(globalThis.__tjs.getStack()).toEqual([])
+      } finally {
+        resetRuntime()
+      }
+    })
+
+    it('no stale entries after mixed success and error calls', () => {
+      const { configure, resetRuntime } = require('./runtime')
+      resetRuntime()
+      configure({ debug: true })
+
+      try {
+        const { code } = tjs(`
+function greet(name: '') -! '' {
+  return 'Hello, ' + name
+}
+`)
+        const greet = new Function(code + '; return greet')()
+
+        // Successful calls
+        greet('Alice')
+        greet('Bob')
+
+        // Error call
+        const err = greet(42)
+        expect(err).toBeInstanceOf(MonadicError)
+
+        // More successful calls
+        greet('Charlie')
+
+        // Stack must be empty throughout
+        expect(globalThis.__tjs.getStack()).toEqual([])
+      } finally {
+        resetRuntime()
+      }
+    })
+
+    it('call stack reflects chain when error occurs at depth', () => {
+      const { configure, resetRuntime } = require('./runtime')
+      resetRuntime()
+      configure({ debug: true })
+
+      try {
+        const { code } = tjs(`/* tjs <- src/pipeline.ts */
+/* line 1 */
+function a(x: 0) -! 0 { return b(x) }
+/* line 3 */
+function b(x: 0) -! 0 { return c(x) }
+/* line 5 */
+function c(x: 0) -! 0 { return d(x) }
+/* line 7 */
+function d(x: '') -! '' { return x.toUpperCase() }
+`)
+        const fns = new Function(code + '; return { a, b, c, d }')()
+        const err = fns.a(99)
+
+        expect(err).toBeInstanceOf(MonadicError)
+        expect(err.path).toBe('src/pipeline.ts:7:d.x')
+
+        // Call stack includes all functions in the chain
+        expect(err.callStack).toEqual([
+          'src/pipeline.ts:1:a',
+          'src/pipeline.ts:3:b',
+          'src/pipeline.ts:5:c',
+          'src/pipeline.ts:7:d',
+        ])
+      } finally {
+        resetRuntime()
+      }
+    })
+  })
+
+  describe('input-side error propagation', () => {
+    it('error from inner function caught by outer input check', () => {
+      const { code } = tjs(`
+function step1(x: '') -! '' {
+  return x.toUpperCase()
+}
+
+function step2(x: '') -! '' {
+  return x + '!'
+}
+`)
+      const fns = new Function(code + '; return { step1, step2 }')()
+
+      // step1(42) returns MonadicError, step2 receives it as input
+      const err = fns.step2(fns.step1(42))
+
+      expect(err).toBeInstanceOf(MonadicError)
+      // Error originated in step1, not step2
+      expect(err.path).toContain('step1.x')
+    })
+
+    it('error identity preserved through chain', () => {
+      const { code } = tjs(`
+function a(x: '') -! '' { return x }
+function b(x: '') -! '' { return x }
+function c(x: '') -! '' { return x }
+`)
+      const fns = new Function(code + '; return { a, b, c }')()
+
+      // Create error at a, flow through b and c
+      const originalError = fns.a(42)
+      expect(originalError).toBeInstanceOf(MonadicError)
+
+      const throughB = fns.b(originalError)
+      const throughC = fns.c(throughB)
+
+      // Same object reference all the way through
+      expect(throughB).toBe(originalError)
+      expect(throughC).toBe(originalError)
+    })
+
+    it('multi-level nested call propagation', () => {
+      const { code } = tjs(`
+function validate(x: '') -! '' { return x }
+function transform(x: '') -! '' { return x.toUpperCase() }
+function format(x: '') -! '' { return x + '!' }
+`)
+      const fns = new Function(
+        code + '; return { validate, transform, format }'
+      )()
+
+      // format(transform(validate(42)))
+      // validate(42) → error, transform(error) → pass-through, format(error) → pass-through
+      const result = fns.format(fns.transform(fns.validate(42)))
+
+      expect(result).toBeInstanceOf(MonadicError)
+      expect(result.path).toContain('validate.x')
+    })
+
+    it('error short-circuits function body', () => {
+      let bodyExecuted = false
+
+      const { code } = tjs(`
+function process(x: '') -! '' {
+  globalThis.__test_body_ran = true
+  return x.toUpperCase()
+}
+`)
+      globalThis.__test_body_ran = false
+      const process = new Function(code + '; return process')()
+
+      // Pass an error — body should NOT execute
+      const inputError = new MonadicError(
+        'upstream',
+        'upstream.x',
+        'string',
+        'number'
+      )
+      const result = process(inputError)
+
+      expect(result).toBe(inputError)
+      expect(globalThis.__test_body_ran).toBe(false)
+
+      delete globalThis.__test_body_ran
+    })
+  })
+
   describe('return type default keys', () => {
     it('signature test passes when optional key is absent', () => {
       const result = tjs(`

package/src/lang/emitters/js-tests.ts

@@ -623,7 +623,8 @@ export function runAllTests(
   // TJS stub setup/restore
   const tjsStub = `
     const __saved_tjs = globalThis.__tjs;
-    const __stub_tjs = { version: '0.0.0', pushStack: () => {}, typeError: (path, expected, value) => new Error(\`Type error at \${path}: expected \${expected}\`), createRuntime: function() { return this; } };
+    class __MonadicError extends Error { constructor(m,p,e,a,c){super(m);this.name='MonadicError';this.path=p;this.expected=e;this.actual=a;this.callStack=c;} }
+    const __stub_tjs = { version: '0.0.0', MonadicError: __MonadicError, pushStack: () => {}, popStack: () => {}, getStack: () => [], typeError: (path, expected, value) => new __MonadicError(\`Type error at \${path}: expected \${expected}\`, path, expected, typeof value), createRuntime: function() { return this; } };
     globalThis.__tjs = __stub_tjs;
   `
   const tjsRestore = `globalThis.__tjs = __saved_tjs;`
@@ -832,7 +833,8 @@ function runTestBlocks(
       // Save and restore globalThis.__tjs to prevent pollution
       const tjsStub = `
         const __saved_tjs = globalThis.__tjs;
-        const __stub_tjs = { version: '0.0.0', pushStack: () => {}, typeError: (path, expected, value) => new Error(\`Type error at \${path}: expected \${expected}\`), createRuntime: function() { return this; } };
+        class __MonadicError extends Error { constructor(m,p,e,a,c){super(m);this.name='MonadicError';this.path=p;this.expected=e;this.actual=a;this.callStack=c;} }
+        const __stub_tjs = { version: '0.0.0', MonadicError: __MonadicError, pushStack: () => {}, popStack: () => {}, getStack: () => [], typeError: (path, expected, value) => new __MonadicError(\`Type error at \${path}: expected \${expected}\`, path, expected, typeof value), createRuntime: function() { return this; } };
         globalThis.__tjs = __stub_tjs;
       `
       const tjsRestore = `globalThis.__tjs = __saved_tjs;`
@@ -1169,7 +1171,8 @@ function runSignatureTest(
     // Save and restore globalThis.__tjs to prevent pollution
     const tjsStub = `
       const __saved_tjs = globalThis.__tjs;
-      const __stub_tjs = { version: '0.0.0', pushStack: () => {}, typeError: (path, expected, value) => new Error(\`Type error at \${path}: expected \${expected}\`), createRuntime: function() { return this; } };
+      class __MonadicError extends Error { constructor(m,p,e,a,c){super(m);this.name='MonadicError';this.path=p;this.expected=e;this.actual=a;this.callStack=c;} }
+      const __stub_tjs = { version: '0.0.0', MonadicError: __MonadicError, pushStack: () => {}, popStack: () => {}, getStack: () => [], typeError: (path, expected, value) => new __MonadicError(\`Type error at \${path}: expected \${expected}\`, path, expected, typeof value), createRuntime: function() { return this; } };
       globalThis.__tjs = __stub_tjs;
     `
     const tjsRestore = `globalThis.__tjs = __saved_tjs;`

package/src/lang/emitters/js.ts

@@ -279,15 +279,12 @@ function generateInlineValidationCode(
   funcName: string,
   types: TJSTypeInfo,
   source?: string
-): string | null {
+): { preamble: string; suffix: string } | null {
   const lines: string[] = []
   // Include source in path if available: "src/file.ts:42:funcName.param"
   const pathPrefix = source ? `${source}:` : ''
   const stackEntry = source ? `${source}:${funcName}` : funcName
 
-  // Push onto call stack for debug mode (only runs if debug enabled)
-  lines.push(`__tjs.pushStack('${stackEntry}');`)
-
   // Destructured params: validate each field of the input object
   if (types.isDestructuredParam && types.destructuredShape) {
     const shape = types.destructuredShape
@@ -321,7 +318,17 @@ function generateInlineValidationCode(
       }
     }
 
-    return lines.length > 0 ? lines.join('\n  ') : null
+    if (lines.length === 0) return null
+
+    // Push stack first, then validate — callStack includes current function
+    // finally block ensures popStack on all exit paths
+    lines.unshift(`__tjs.pushStack('${stackEntry}');`)
+    lines.unshift(`try {`)
+
+    return {
+      preamble: lines.join('\n  '),
+      suffix: '} finally { __tjs.popStack(); }',
+    }
   }
 
   // Positional params: validate each param
@@ -352,7 +359,17 @@ function generateInlineValidationCode(
     }
   }
 
-  return lines.length > 0 ? lines.join('\n  ') : null
+  if (lines.length === 0) return null
+
+  // Push stack first, then validate — callStack includes current function
+  // finally block ensures popStack on all exit paths
+  lines.unshift(`__tjs.pushStack('${stackEntry}');`)
+  lines.unshift(`try {`)
+
+  return {
+    preamble: lines.join('\n  '),
+    suffix: '} finally { __tjs.popStack(); }',
+  }
 }
 
 /**
@@ -612,16 +629,21 @@ export function transpileToJS(
     // Skip for unsafe functions and polymorphic dispatchers (they handle routing)
     if (!isUnsafe && !isPolymorphicDispatcher) {
       const sourceStr = `${funcLoc.file}:${funcLoc.line}`
-      const validationCode = generateInlineValidationCode(
+      const validation = generateInlineValidationCode(
         funcName,
         types,
         sourceStr
       )
-      if (validationCode && func.body && func.body.start !== undefined) {
-        // Insert right after the opening brace
+      if (validation && func.body && func.body.start !== undefined) {
+        // Insert preamble right after the opening brace
         insertions.push({
           position: func.body.start + 1,
-          text: `\n  ${validationCode}\n`,
+          text: `\n  ${validation.preamble}\n`,
+        })
+        // Insert suffix (popStack) right before the closing brace
+        insertions.push({
+          position: func.body.end - 1,
+          text: `\n  ${validation.suffix}\n`,
         })
       }
     }
@@ -638,11 +660,12 @@ export function transpileToJS(
   // Add __tjs reference for monadic error handling and structural equality
   // Use createRuntime() for isolated state per-module
   const needsTypeError = code.includes('__tjs.typeError(')
+  const needsStack = code.includes('__tjs.pushStack(')
   const needsIs = code.includes('Is(')
   const needsIsNot = code.includes('IsNot(')
   const needsSafeEval = preprocessed.tjsModes.tjsSafeEval
 
-  if (needsTypeError || needsIs || needsIsNot || needsSafeEval) {
+  if (needsTypeError || needsStack || needsIs || needsIsNot || needsSafeEval) {
     // Create isolated runtime instance for this module
     // Falls back to shared global if createRuntime not available
     let preamble =
@@ -906,7 +929,7 @@ function canUseInlineValidation(types: TJSTypeInfo): boolean {
  *   if (typeof input !== 'object' || input === null ||
  *       typeof input.x !== 'number' ||
  *       typeof input.y !== 'number') {
- *     return { $error: true, message: '...', path: 'funcName.input' }
+ *     return __tjs.typeError('funcName.input', 'object', input)
  *   }
  */
 export function generateInlineValidation(
@@ -942,7 +965,7 @@ export function generateInlineValidation(
   if (checks.length === 0) return ''
 
   return `if (${checks.join(' || ')}) {
-  return { $error: true, message: 'Invalid ${paramName}', path: '${path}' }
+  return __tjs.typeError('${path}', 'object', ${paramName})
 }`
 }
 
@@ -997,7 +1020,7 @@ const generateTypeCheck = generateTypeCheckExpr
  *   const _original_funcName = funcName
  *   funcName = function(__input) {
  *     if (typeof __input !== 'object' || __input === null || ...) {
- *       return { $error: true, message: '...', path: '...' }
+ *       return __tjs.typeError('funcName.input', 'object', __input)
  *     }
  *     return _original_funcName.call(this, __input)
  *   }

package/src/lang/features.test.ts

@@ -799,9 +799,9 @@ function parse(s: '') {
   }
 }
 `)
-    // Should add a catch block that returns monadic error
+    // Should add a catch block that returns a MonadicError
     expect(result.source).toContain('catch (__try_err)')
-    expect(result.source).toContain('$error: true')
+    expect(result.source).toContain('MonadicError')
     expect(result.source).toContain('__try_err?.message')
   })
 
@@ -851,7 +851,7 @@ function safeParse(s: '') {
     )
     // The transpiled code should have the monadic error catch
     expect(result.code).toContain('catch (__try_err)')
-    expect(result.code).toContain('$error: true')
+    expect(result.code).toContain('MonadicError')
   })
 
   it('monadic error should have proper structure', () => {
@@ -861,11 +861,10 @@ function test() {
   try { throw new Error('oops') }
 }
 `)
-    // Check error structure
-    expect(result.source).toContain("op: 'try'")
-    expect(result.source).toContain('cause: __try_err')
-    // Should capture call stack for debugging
-    expect(result.source).toContain('stack: globalThis.__tjs?.getStack?.()')
+    // Should return a MonadicError to maintain monadic flow
+    expect(result.source).toContain('MonadicError')
+    expect(result.source).toContain('__try_err?.message')
+    expect(result.source).toContain('return new')
   })
 })
 

package/src/lang/parser-transforms.ts

@@ -51,10 +51,10 @@ export function transformTryWithoutCatch(source: string): string {
         result += source.slice(i, j)
         i = j
       } else {
-        // No catch or finally - add monadic error handler with call stack
-        // In debug mode, __tjs.getStack() returns the call stack for diagnostics
+        // No catch or finally - add monadic error handler
+        // Returns MonadicError to maintain monadic flow (propagates through function chains)
         const body = source.slice(bodyStart, j - 1)
-        result += `try {${body}} catch (__try_err) { return { $error: true, message: __try_err?.message || String(__try_err), op: 'try', cause: __try_err, stack: globalThis.__tjs?.getStack?.() } }`
+        result += `try {${body}} catch (__try_err) { return new (__tjs?.MonadicError ?? Error)(__try_err?.message || String(__try_err), 'try', undefined, undefined, __tjs?.getStack?.()) }`
         i = j
       }
     } else {

package/src/lang/perf.test.ts

@@ -366,7 +366,7 @@ describe('TJS Performance', () => {
       // Sanity check
       expect(tryThrow(42)).toBe(42)
       const err = tryThrow(-1)
-      expect(err.$error).toBe(true)
+      expect(err).toBeInstanceOf(Error)
     })
   })
 

package/src/lang/roundtrip.test.ts

@@ -12,7 +12,7 @@
 
 import { describe, test, expect, beforeAll } from 'bun:test'
 import { tjs } from './index'
-import { Is, IsNot } from './runtime'
+import { Is, IsNot, MonadicError } from './runtime'
 
 // Set up the minimal runtime needed for transpiled code
 beforeAll(() => {
@@ -21,12 +21,15 @@ beforeAll(() => {
     IsNot,
     pushStack: () => {},
     popStack: () => {},
+    MonadicError,
     typeError: (path: string, expected: string, got: any) => {
-      const err = new Error(
-        `Type error at ${path}: expected ${expected}, got ${typeof got}`
+      const actual = got === null ? 'null' : typeof got
+      return new MonadicError(
+        `Expected ${expected} for '${path}', got ${actual}`,
+        path,
+        expected,
+        actual
       )
-      ;(err as any).$error = true
-      return err
     },
     createRuntime: () => (globalThis as any).__tjs,
   }