rip-lang 3.1.1 → 3.2.0

package/docs/RIP-TYPES.md

@@ -1,46 +1,19 @@
-# Optional Types in Rip
+# Rip Types
 
-> **Type-Driven Development Without the Overhead**
+> **Types describe what you mean. Code does what you say.**
 
-This specification defines Rip's optional, lightweight type system — a thin, compile-time-only layer that enables TypeScript-level type-driven development while preserving Rip's core philosophy: minimal syntax, high readability, zero runtime overhead.
+Rip supports an optional, lightweight, expressive way to design software by
+defining shapes, intent, and contracts up front — without enforcing types at
+runtime or burdening the language with a full type system.
 
----
-
-## Table of Contents
-
-1. [Philosophy](#1-philosophy)
-2. [Type Annotations](#2-type-annotations)
-3. [Type Aliases](#3-type-aliases)
-4. [Optionality Modifiers](#4-optionality-modifiers)
-5. [Structural Types](#5-structural-types)
-6. [Union Types](#6-union-types)
-7. [Function Types](#7-function-types)
-8. [Generic Types](#8-generic-types)
-9. [Type Inference](#9-type-inference)
-10. [Adoption Model](#10-adoption-model)
-11. [Emission Strategy](#11-emission-strategy)
-12. [Interfaces](#12-interfaces)
-13. [Enums](#13-enums)
-14. [Boundary Validation](#14-boundary-validation)
-15. [Implementation Notes](#15-implementation-notes)
-16. [Quick Reference](#16-quick-reference)
-
----
-
-# 1. Philosophy
-
-## Core Principles
+Types in Rip are:
 
-1. **Types are additive, never required** — Rip code without types is valid Rip code
-2. **All type syntax erases at runtime** — Zero performance cost
-3. **Type syntax decorates existing constructs** — No new control flow or semantics
-4. **No typechecker required in Rip** — Parse and preserve, don't enforce
-5. **Emit TypeScript-compatible types** — Leverage existing tooling
-6. **Prefer zero-runtime representations** — Unions over enums, types over classes
+- **Optional** — Rip code without types is valid Rip code
+- **Erased at runtime** — Zero performance cost
+- **TypeScript-compatible** — Emit `.d.ts` files, leverage existing tooling
+- **Editor-driven** — Autocompletion, hover info, refactoring support
 
-## The Rip Way
-
-Types in Rip should feel like documentation that happens to be machine-readable:
+Rip treats types as *design scaffolding*, not safety rails.
 
 ```coffee
 # Without types (valid)
@@ -52,41 +25,83 @@ def greet(name:: string):: string
   "Hello, #{name}!"
 ```
 
-Both compile to identical JavaScript. Types exist for developers and tools, not for the runtime.
+Both compile to identical JavaScript.
 
-## Static Typing as a Discipline, Not a Mandate
+---
 
-Rip's type system is designed for teams and projects that want:
+## Table of Contents
 
-- **IDE intelligence** — Autocompletion, hover info, refactoring support
-- **Documentation** — Self-documenting function signatures
-- **Boundary safety** — Confidence at API and module boundaries
-- **Gradual adoption** — Add types where they matter, skip where they don't
+1. [Type Sigil Reference](#type-sigil-reference)
+2. [Type Annotations (`::`)](#type-annotations-)
+3. [Type Aliases (`::=`)](#type-aliases-)
+4. [Structural Types](#structural-types)
+5. [Optionality Modifiers](#optionality-modifiers)
+6. [Union Types](#union-types)
+7. [Function Types](#function-types)
+8. [Generic Types](#generic-types)
+9. [Interfaces](#interfaces)
+10. [Enums](#enums)
+11. [Type Inference](#type-inference)
+12. [Adoption Model](#adoption-model)
+13. [Emission Strategy](#emission-strategy)
+14. [Boundary Validation](#boundary-validation)
+15. [Editor-First Workflow](#editor-first-workflow)
+16. [What Rip Intentionally Does Not Do](#what-rip-intentionally-does-not-do)
+17. [Implementation Plan](#implementation-plan)
 
 ---
 
-# 2. Type Annotations
+## Type Sigil Reference
+
+| Sigil | Meaning | Example |
+|-------|---------|---------|
+| `::` | Type annotation | `count:: number = 0` |
+| `::=` | Type alias | `ID ::= number` |
+| `?` | Optional value (`T \| undefined`) | `email:: string?` |
+| `??` | Nullable value (`T \| null \| undefined`) | `middle:: string??` |
+| `!` | Non-nullable (`NonNullable<T>`) | `id:: ID!` |
+| `?:` | Optional property | `email?: string` |
+| `\|` | Union member | `"a" \| "b" \| "c"` |
+| `=>` | Function type arrow | `(a: number) => string` |
+| `<T>` | Generic parameter | `Container<T>` |
 
-## Syntax: `::`
+This is the complete Rip Types sigil vocabulary.
 
-The double-colon `::` annotates types on variables, parameters, return values, and properties.
+---
+
+## Type Annotations (`::`)
+
+The double-colon `::` annotates types on variables, parameters, return values,
+and properties.
 
 ### Variables
 
 ```coffee
 count:: number = 0
 name:: string = "Rip"
-active:: boolean = true
 items:: string[] = []
 ```
 
-**Emits to TypeScript:**
+**Emits:**
+
+```ts
+let count: number; count = 0;
+let name: string; name = "Rip";
+let items: string[]; items = [];
+```
+
+### Constants
+
+```coffee
+MAX_RETRIES:: number =! 3
+API_URL:: string =! "https://api.example.com"
+```
+
+**Emits:**
 
 ```ts
-let count: number = 0;
-let name: string = "Rip";
-let active: boolean = true;
-let items: string[] = [];
+const MAX_RETRIES: number = 3;       // =! emits const
+const API_URL: string = "https://api.example.com";
 ```
 
 ### Function Parameters
@@ -131,18 +146,10 @@ def processUser(id:: number, options:: Options):: Result
   transform(user, options)
 ```
 
-### Constants
-
-```coffee
-MAX_RETRIES:: number =! 3
-API_URL:: string =! "https://api.example.com"
-```
-
 **Emits:**
 
 ```ts
-const MAX_RETRIES: number = 3;
-const API_URL: string = "https://api.example.com";
+function processUser(id: number, options: Options): Result { ... }
 ```
 
 ### Reactive State
@@ -150,24 +157,33 @@ const API_URL: string = "https://api.example.com";
 Types work with Rip's reactive operators:
 
 ```coffee
-count:: number := 0           # Reactive state with type
-doubled:: number ~= count * 2  # Computed with type
+count:: number := 0
+doubled:: number ~= count * 2
 ```
 
----
+**Emits:**
 
-# 3. Type Aliases
+```ts
+const count = __state<number>(0);       // := emits const
+const doubled = __computed<number>(() => count * 2);  // ~= emits const
+```
 
-## Syntax: `::=`
+---
 
-The `::=` operator declares a named type alias, mapping directly to TypeScript's `type X = ...`.
+## Type Aliases (`::=`)
 
-### Simple Aliases
+The `::=` operator declares a named type, mapping directly to TypeScript's
+`type X = ...`.
 
 ```coffee
+# Simple aliases
 ID ::= number
 Name ::= string
-Timestamp ::= number
+
+# Complex types
+UserID ::= number | string
+Callback ::= (error:: Error?, data:: any) => void
+Handler ::= (req:: Request, res:: Response) => Promise<void>
 ```
 
 **Emits:**
@@ -175,32 +191,100 @@ Timestamp ::= number
 ```ts
 type ID = number;
 type Name = string;
-type Timestamp = number;
+
+type UserID = number | string;
+type Callback = (error: Error | undefined, data: any) => void;
+type Handler = (req: Request, res: Response) => Promise<void>;
 ```
 
-### Complex Types
+---
+
+## Structural Types
+
+Define object shapes using the `type` keyword followed by a block:
 
 ```coffee
-UserID ::= number | string
-Callback ::= (error:: Error?, data:: any) -> void
-Handler ::= (req:: Request, res:: Response) -> Promise<void>
+User ::= type
+  id: number
+  name: string
+  email?: string
+  createdAt: Date
+
+Config ::= type
+  host: string
+  port: number
+  ssl?: boolean
+  timeout?: number
 ```
 
 **Emits:**
 
 ```ts
-type UserID = number | string;
-type Callback = (error: Error | undefined, data: any) => void;
-type Handler = (req: Request, res: Response) => Promise<void>;
+type User = {
+  id: number;
+  name: string;
+  email?: string;
+  createdAt: Date;
+};
+
+type Config = {
+  host: string;
+  port: number;
+  ssl?: boolean;
+  timeout?: number;
+};
+```
+
+### Nesting, Readonly, and Index Signatures
+
+```coffee
+Response ::= type
+  data: type
+    users: User[]
+    total: number
+  meta: type
+    page: number
+    limit: number
+
+ImmutableConfig ::= type
+  readonly host: string
+  readonly port: number
+
+Dictionary ::= type
+  [key: string]: any
+```
+
+**Emits:**
+
+```ts
+type Response = {
+  data: {
+    users: User[];
+    total: number;
+  };
+  meta: {
+    page: number;
+    limit: number;
+  };
+};
+
+type ImmutableConfig = {
+  readonly host: string;
+  readonly port: number;
+};
+
+type Dictionary = {
+  [key: string]: any;
+};
 ```
 
 ---
 
-# 4. Optionality Modifiers
+## Optionality Modifiers
 
 Lightweight suffix operators that map directly to TypeScript unions.
 
-## Optional: `T?`
+### Optional: `T?`
 
 Indicates a value may be undefined.
 
@@ -216,7 +300,7 @@ email: string | undefined
 callback: Function | undefined
 ```
 
-## Nullable Optional: `T??`
+### Nullable Optional: `T??`
 
 Indicates a value may be null or undefined.
 
@@ -232,7 +316,7 @@ middle: string | null | undefined
 cache: Map<string, any> | null | undefined
 ```
 
-## Non-Nullable: `T!`
+### Non-Nullable: `T!`
 
 Asserts a value is never null or undefined.
 
@@ -248,7 +332,7 @@ id: NonNullable<ID>
 user: NonNullable<User>
 ```
 
-## In Function Signatures
+### In Function Signatures
 
 ```coffee
 def findUser(id:: number):: User?
@@ -261,38 +345,25 @@ def updateUser(id:: number, email:: string??):: boolean
   ...
 ```
 
-## Optional Properties
-
-In object types, `?` after the property name makes it optional:
+**Emits:**
 
-```coffee
-User ::= type
-  id: number
-  name: string
-  email?: string      # Optional property
-  phone?: string?     # Optional property that can also be undefined when present
+```ts
+function findUser(id: number): User | undefined { ... }
+function getUser(id: number): NonNullable<User> { ... }
+function updateUser(id: number, email: string | null | undefined): boolean { ... }
 ```
 
----
-
-# 5. Structural Types
+### Optional Properties
 
-## Object Types with `type` Block
-
-Define structural types using the `type` keyword followed by a block:
+In structural types, `?` after the property name makes it optional (the
+property itself may be absent), distinct from value optionality:
 
 ```coffee
 User ::= type
   id: number
   name: string
-  email?: string
-  createdAt: Date
-
-Config ::= type
-  host: string
-  port: number
-  ssl?: boolean
-  timeout?: number
+  email?: string      # Optional property — may be absent
+  phone?: string?     # Optional property that can also be undefined when present
 ```
 
 **Emits:**
@@ -302,93 +373,32 @@ type User = {
   id: number;
   name: string;
   email?: string;
-  createdAt: Date;
-};
-
-type Config = {
-  host: string;
-  port: number;
-  ssl?: boolean;
-  timeout?: number;
-};
-```
-
-## Nested Types
-
-```coffee
-Response ::= type
-  data: type
-    users: User[]
-    total: number
-  meta: type
-    page: number
-    limit: number
-```
-
-**Emits:**
-
-```ts
-type Response = {
-  data: {
-    users: User[];
-    total: number;
-  };
-  meta: {
-    page: number;
-    limit: number;
-  };
+  phone?: string | undefined;
 };
 ```
 
-## Array Properties
-
-```coffee
-Collection ::= type
-  items: Item[]
-  tags: string[]
-  matrix: number[][]
-```
-
-## Readonly Properties
+### Key Distinction
 
-```coffee
-ImmutableConfig ::= type
-  readonly host: string
-  readonly port: number
-```
-
-## Index Signatures
-
-```coffee
-Dictionary ::= type
-  [key: string]: any
-
-StringMap ::= type
-  [key: string]: string
-```
+- `email?: string` — property may be absent
+- `email:: string?` — value may be undefined
+- `email?: string??` — property may be absent, value may be null or undefined
 
 ---
 
-# 6. Union Types
+## Union Types
 
-## Inline Unions
+### Inline
 
 ```coffee
 Status ::= "pending" | "active" | "done"
 Result ::= Success | Error
-ID ::= number | string
 ```
 
-## Block Unions (Preferred)
+### Block Form (Preferred)
 
-For readability and diff-friendliness, use the block form with leading `|`:
+Vertical form is diff-friendly and encourages domain-first modeling:
 
 ```coffee
-Status ::=
-  | "pending"
-  | "active"
-  | "done"
-
 HttpMethod ::=
   | "GET"
   | "POST"
@@ -413,105 +423,66 @@ type Result =
   | { success: false; error: Error };
 ```
 
-## Why Block Unions Over Enums
-
-Block unions have **zero runtime cost** — they exist only at compile time. Traditional enums generate runtime code:
-
-```coffee
-# Preferred: Zero runtime cost
-Size ::=
-  | "xs"
-  | "sm"
-  | "md"
-  | "lg"
-
-# Avoid: Generates runtime object
-enum Size
-  xs
-  sm
-  md
-  lg
-```
+### Why Unions Over Enums
 
-Use enums only when you need:
-- Reverse mapping (value → name)
-- Runtime iteration over values
-- Explicit numeric values
+Block unions have **zero runtime cost** — they exist only at compile time.
+Use enums only when you need reverse mapping, runtime iteration, or explicit
+numeric values.
 
 ---
 
-# 7. Function Types
-
-## Arrow Function Types
+## Function Types
 
 ```coffee
-Comparator ::= (a:: any, b:: any) -> number
-AsyncFetcher ::= (url:: string) -> Promise<Response>
-Callback ::= (err:: Error?, data:: any?) -> void
-```
-
-**Emits:**
-
-```ts
-type Comparator = (a: any, b: any) => number;
-type AsyncFetcher = (url: string) => Promise<Response>;
-type Callback = (err: Error | undefined, data: any | undefined) => void;
-```
+# Type aliases for function signatures
+Comparator ::= (a:: any, b:: any) => number
+AsyncFetcher ::= (url:: string) => Promise<Response>
 
-## Function Overloads
-
-Multiple signatures for a single implementation:
-
-```coffee
-# Overload signatures
+# Overloads
 def toHtml(content:: string):: string
 def toHtml(nodes:: Element[]):: string
-def toHtml(fragment:: DocumentFragment):: string
-
-# Implementation (matches last signature or uses widest type)
 def toHtml(input:: any):: string
   switch typeof input
     when "string" then escapeHtml(input)
     else renderNodes(input)
+
+# Method signatures in classes
+class UserService
+  find: (id:: number):: User? ->
+    @db.find(id)
+
+  create: (data:: CreateUserInput):: User ->
+    @db.create(data)
 ```
 
 **Emits:**
 
 ```ts
+type Comparator = (a: any, b: any) => number;
+type AsyncFetcher = (url: string) => Promise<Response>;
+
 function toHtml(content: string): string;
 function toHtml(nodes: Element[]): string;
-function toHtml(fragment: DocumentFragment): string;
 function toHtml(input: any): string {
   // implementation
 }
-```
-
-## Method Signatures in Classes
 
-```coffee
-class UserService
-  find: (id:: number):: User? ->
-    @db.find(id)
-
-  create: (data:: CreateUserInput):: User ->
-    @db.create(data)
-
-  update: (id:: number, data:: UpdateUserInput):: User? ->
-    @db.update(id, data)
+class UserService {
+  find(id: number): User | undefined { ... }
+  create(data: CreateUserInput): User { ... }
+}
 ```
 
 ---
 
-# 8. Generic Types
-
-## Generic Type Parameters
+## Generic Types
 
 ```coffee
 # Simple generic
 Container<T> ::= type
   value: T
 
-# Multiple type parameters
+# Multiple parameters
 Pair<K, V> ::= type
   key: K
   value: V
@@ -519,7 +490,17 @@ Pair<K, V> ::= type
 # With constraints
 Comparable<T extends Ordered> ::= type
   value: T
-  compareTo: (other:: T) -> number
+  compareTo: (other:: T) => number
+
+# Generic functions
+def identity<T>(value:: T):: T
+  value
+
+def map<T, U>(items:: T[], fn:: (item:: T) => U):: U[]
+  items.map(fn)
+
+def merge<T extends object, U extends object>(a:: T, b:: U):: T & U
+  {...a, ...b}
 ```
 
 **Emits:**
@@ -538,65 +519,118 @@ type Comparable<T extends Ordered> = {
   value: T;
   compareTo: (other: T) => number;
 };
+
+function identity<T>(value: T): T { ... }
+function map<T, U>(items: T[], fn: (item: T) => U): U[] { ... }
+function merge<T extends object, U extends object>(a: T, b: U): T & U { ... }
 ```
 
-## Generic Functions
+---
 
-```coffee
-def identity<T>(value:: T):: T
-  value
+## Interfaces
 
-def map<T, U>(items:: T[], fn:: (item:: T) -> U):: U[]
-  items.map(fn)
+For TypeScript compatibility, Rip supports the `interface` keyword:
 
-def first<T>(items:: T[]):: T?
-  items[0]
+```coffee
+interface Animal
+  name: string
+
+interface Dog extends Animal
+  breed: string
+  bark: () => void
 ```
 
-## Generic Constraints
+**Emits:**
 
-```coffee
-def merge<T extends object, U extends object>(a:: T, b:: U):: T & U
-  {...a, ...b}
+```ts
+interface Animal {
+  name: string;
+}
 
-def stringify<T extends { toString: () -> string }>(value:: T):: string
-  value.toString()
+interface Dog extends Animal {
+  breed: string;
+  bark: () => void;
+}
 ```
 
+Use `::= type` by default. Use `interface` when you need declaration merging.
+
 ---
 
-# 9. Type Inference
+## Enums
+
+### Zero-Runtime (Preferred)
+
+```coffee
+Size ::=
+  | "xs"
+  | "sm"
+  | "md"
+  | "lg"
+  | "xl"
+```
+
+**Emits to `.d.ts` only:**
+
+```ts
+type Size = "xs" | "sm" | "md" | "lg" | "xl";
+```
+
+### Runtime Enums (When Needed)
+
+```coffee
+enum HttpCode
+  ok = 200
+  created = 201
+  notFound = 404
+  serverError = 500
+```
+
+**Emits to both `.js` and `.d.ts`:**
+
+```ts
+// .d.ts
+enum HttpCode {
+  ok = 200,
+  created = 201,
+  notFound = 404,
+  serverError = 500
+}
+
+// .js (runtime object with reverse mapping)
+const HttpCode = {
+  ok: 200, created: 201, notFound: 404, serverError: 500,
+  200: "ok", 201: "created", 404: "notFound", 500: "serverError"
+};
+```
 
-## When to Annotate
+Runtime enums generate a reverse-mapping object. Use only when you need
+`HttpCode[200]` → `"ok"` or runtime iteration.
+
+---
 
-Rip's type system uses **TypeScript-compatible inference**. Types should be explicit at boundaries, optional elsewhere:
+## Type Inference
 
-### Explicit (Recommended)
+Types should be explicit at boundaries, optional elsewhere:
 
 ```coffee
-# Function signatures — always annotate
-def processUser(id:: number, options:: ProcessOptions):: Result
+# Explicit — function signatures, exports, class properties
+def processUser(id:: number, options:: Options):: Result
   ...
 
-# Exported values — always annotate
 export config:: Config = loadConfig()
 
-# Class properties — annotate for clarity
 class UserService
   db:: Database
   cache:: Map<string, User>
-```
-
-### Inferred (Acceptable)
 
-```coffee
-# Local variables — let TypeScript infer
-user = getUser!(id)        # Inferred from getUser's return type
+# Inferred — local variables
+user = getUser!(id)           # Inferred from return type
 items = users.map (u) -> u.name  # Inferred as string[]
-count = 0                  # Inferred as number
+count = 0                     # Inferred as number
 ```
 
-## Inference Rules
+### Inference Rules
 
 1. **Function returns** — Inferred from body if not annotated
 2. **Variables** — Inferred from initializer
@@ -605,13 +639,11 @@ count = 0                  # Inferred as number
 
 ---
 
-# 10. Adoption Model
-
-Types are optional at three levels: project, file, and line.
+## Adoption Model
 
-## Project Level
+Types are optional at every level:
 
-Configure in `package.json` or `rip.config.json`:
+### Project Level
 
 ```json
 {
@@ -623,38 +655,21 @@ Configure in `package.json` or `rip.config.json`:
 
 | Mode | Behavior |
 |------|----------|
-| `"off"` | Ignore all type syntax (strip during parse) |
-| `"emit"` | Parse types, emit `.d.ts` files |
-| `"check"` | Parse types, emit `.d.ts`, run `tsc --noEmit` |
-
-## File Level
-
-Override project settings per-file with a directive comment:
-
-```coffee
-# @types off
-# This file has no type checking
+| `"off"` | Types are parsed but ignored — no `.d.ts` emitted |
+| `"emit"` | `.d.ts` files generated — enables editor IntelliSense |
+| `"check"` | `.d.ts` generated + `tsc --noEmit` validates types |
 
-# @types emit
-# Types parsed and emitted for this file
+### File Level
 
-# @types check
-# Types checked via TypeScript for this file
-```
-
-## Line Level
-
-All type syntax is simply ignored if types are disabled. No special syntax needed — annotations silently disappear:
+Override per-file with a directive:
 
 ```coffee
-# With types enabled:
-count:: number = 0  # Type preserved
-
-# With types disabled:
-count:: number = 0  # Parses as: count = 0
+# @types off    — Ignore types in this file
+# @types emit   — Parse and emit .d.ts
+# @types check  — Full TypeScript checking
 ```
 
-## Gradual Adoption Path
+### Gradual Path
 
 1. **Start with `"off"`** — Write normal Rip code
 2. **Enable `"emit"`** — Add types where helpful, get `.d.ts` for tooling
@@ -662,18 +677,16 @@ count:: number = 0  # Parses as: count = 0
 
 ---
 
-# 11. Emission Strategy
-
-## Compilation Outputs
+## Emission Strategy
 
 | Input | Output | Purpose |
 |-------|--------|---------|
 | `file.rip` | `file.js` | Runtime code (always) |
 | `file.rip` | `file.d.ts` | Type declarations (when `emit` or `check`) |
 
-## Type Declaration Files
-
-When `types: "emit"` or `types: "check"`, generate `.d.ts` files:
+Type aliases and annotations are stripped from `.js` output and preserved
+in `.d.ts` output. Type-only declarations (`::=` aliases, unions) appear
+only in `.d.ts`.
 
 ```coffee
 # user.rip
@@ -685,18 +698,7 @@ export def getUser(id:: number):: User?
   db.find(id)
 ```
 
-**Generates `user.d.ts`:**
-
-```ts
-export type User = {
-  id: number;
-  name: string;
-};
-
-export function getUser(id: number): User | undefined;
-```
-
-**Generates `user.js`:**
+**Generates `user.js`** — types erased:
 
 ```js
 export function getUser(id) {
@@ -704,426 +706,1174 @@ export function getUser(id) {
 }
 ```
 
-## Type-Only Exports
+**Generates `user.d.ts`** — types preserved:
 
-Type aliases that have no runtime representation are only emitted to `.d.ts`:
+```ts
+export type User = { id: number; name: string; };
+export function getUser(id: number): User | undefined;
+```
+
+---
+
+## Boundary Validation
+
+Types are compile-time contracts. For data entering your system, validate
+at boundaries:
 
 ```coffee
-# These only appear in .d.ts, not .js
-Status ::= "pending" | "active" | "done"
-UserID ::= number
+import { z } from "zod"
+
+# Define schema (runtime validation + type source of truth)
+UserSchema = z.object
+  id: z.number()
+  name: z.string()
+  email: z.string().email()
+
+# Derive type from schema
+User ::= z.infer<typeof UserSchema>
+
+# Validate at API boundary
+def createUser(req:: Request):: User
+  data = req.json!
+  UserSchema.parse(data)
 ```
 
-## Integration with TypeScript
+Once data passes boundary validation, trust the types internally — no need
+to re-validate.
+
+---
+
+## Editor-First Workflow
 
-When `types: "check"`:
+Rip Types is primarily **editor-driven**. The intended loop:
 
-1. Compile `.rip` → `.js` + `.d.ts`
-2. Run `tsc --noEmit` to validate types
-3. Report TypeScript errors
+1. Define shapes and contracts
+2. Annotate public boundaries
+3. Let the editor guide implementation
+4. Optionally validate via `types: "check"`
 
-This leverages TypeScript's mature type checker without reimplementing it.
+High-quality `.d.ts` output is a first-class goal.
 
 ---
 
-# 12. Interfaces
+## What Rip Intentionally Does Not Do
 
-## Syntax: `interface`
+Rip does not:
 
-For TypeScript compatibility, Rip also supports the `interface` keyword for object types:
+- Narrow types based on control flow
+- Perform exhaustiveness checks
+- Reject programs based on type errors
+- Introduce runtime type checks
+- Evaluate type expressions or prove soundness
 
-```coffee
-interface User
-  id: number
-  name: string
-  email?: string
-```
+These responsibilities belong to editors, linters, and TypeScript tooling
+(when enabled via `types: "check"`).
 
-**Emits:**
+Rip only needs to:
 
-```ts
-interface User {
-  id: number;
-  name: string;
-  email?: string;
-}
-```
+- **Parse** type syntax correctly
+- **Preserve** type information in the AST
+- **Emit** valid TypeScript type declarations
 
-## Type vs Interface
+---
 
-| Feature | `::= type` | `interface` |
-|---------|------------|-------------|
-| Declaration merging | No | Yes |
-| Extends | Via `&` intersection | Via `extends` |
-| Computed properties | Yes | No |
-| Mapped types | Yes | No |
+## Summary
 
-**Recommendation:** Use `::= type` by default. Use `interface` when you need declaration merging or prefer the interface aesthetic.
+Rip Types provides:
 
-## Interface Extension
+- Expressive domain modeling with minimal syntax
+- Gradual adoption — add types where they help
+- Zero runtime overhead — types are compile-time only
+- Excellent editor intelligence via `.d.ts` emission
+- Clean interop with the TypeScript ecosystem
 
-```coffee
-interface Animal
-  name: string
+Rip remains a **JavaScript language**, with types as a **design language**
+layered on top.
 
-interface Dog extends Animal
-  breed: string
-  bark: () -> void
-```
+> **Static typing as a discipline, not a mandate.**
 
 ---
 
-# 13. Enums
+## Implementation Plan
 
-## Zero-Runtime Enums (Preferred)
+This section describes how to implement Rip Types in the compiler. It is
+designed to be self-contained — an implementor should be able to read this
+section and the referenced source files and complete the work in one pass.
 
-Use string literal unions for zero runtime cost:
+> **Interoperability Principle.** Rip Types emits standard TypeScript `.d.ts`
+> declaration files — the same format any TypeScript project produces. The
+> goal is full ecosystem interoperability. A Rip library's types are
+> indistinguishable from hand-written TypeScript to any consumer. Rip
+> developers get IDE autocompletion and type checking for third-party
+> packages (React, Express, etc.) through the TypeScript Language Server,
+> which reads standard `.d.ts` files from `node_modules`. Rip is a
+> participant in the TypeScript ecosystem, not a replacement for it.
 
-```coffee
-Size ::=
-  | "xs"
-  | "sm"
-  | "md"
-  | "lg"
-  | "xl"
+### File Architecture
+
+Rip Types follows the same sidecar pattern as the component system.
+Components added `src/components.js` alongside the compiler — types add
+`src/types.js` alongside the lexer:
+
+| File | Role | Scope |
+|------|------|-------|
+| `src/lexer.js` | Detect `::` and `::=` tokens, import `installTypeSupport` from `types.js` | Small inline changes |
+| `src/types.js` | Lexer sidecar: `installTypeSupport(Lexer)`, `emitTypes(tokens)`, `generateEnum()` | New file, bulk of logic |
+| `src/compiler.js` | Call `emitTypes()` before parsing, wire `generateEnum()` | ~8 lines |
+| `src/grammar/grammar.rip` | Add `Enum` rule to `Expression` | 1 rule + 1 export |
+
+The boundary is the token stream. Types are fully resolved before parsing —
+`rewriteTypes()` strips annotations, `emitTypes()` produces `.d.ts` from
+annotated tokens, and type-only constructs are removed before the parser
+runs. Only `enum` crosses into the parser/compiler because it generates
+runtime JavaScript.
+
+**The `components.js` pattern to follow:**
+
+```js
+// src/components.js — existing sidecar for the compiler
+export function installComponentSupport(CodeGenerator) {
+  const proto = CodeGenerator.prototype;
+  proto.generateComponent = function(head, rest, context) { ... };
+  proto.generateRender = function(head, rest, context, sexpr) { ... };
+  proto.buildRender = function(body) { ... };
+  // ...
+}
 
-Direction ::=
-  | "north"
-  | "south"
-  | "east"
-  | "west"
+// src/compiler.js — existing wiring
+import { installComponentSupport } from './components.js';
+installComponentSupport(CodeGenerator);  // at module level, after class definition
 ```
 
-**Emits only to `.d.ts`:**
+**The parallel for types:**
 
-```ts
-type Size = "xs" | "sm" | "md" | "lg" | "xl";
-type Direction = "north" | "south" | "east" | "west";
+```js
+// src/types.js — new sidecar for the lexer
+export function installTypeSupport(Lexer) {
+  Lexer.prototype.rewriteTypes = function() { ... };  // Uses this.scanTokens()
+}
+export function emitTypes(tokens) { ... }           // Annotated tokens -> .d.ts string
+export function generateEnum(head, rest, ctx) { ... } // Enum -> runtime JS object
+
+// src/lexer.js — wiring (mirrors compiler.js wiring for components)
+import { installTypeSupport } from './types.js';
+installTypeSupport(Lexer);
+
+// src/compiler.js — wiring
+import { emitTypes, generateEnum } from './types.js';
+CodeGenerator.prototype.generateEnum = generateEnum;
+CodeGenerator.GENERATORS['enum'] = 'generateEnum';
+// In compile(): let dts = emitTypes(tokens);
 ```
 
-## Runtime Enums (When Needed)
+### Phase 1: Type Annotations (Metadata on Existing Tokens)
 
-When you need runtime access to enum values, use the `enum` keyword:
+Type annotations on variables, parameters, return types, and reactive state
+ride as **metadata** on existing tokens. The grammar never sees them. This
+means all existing grammar rules, s-expression shapes, and codegen work
+unchanged — types are invisible to everything except `rewriteTypes()` and
+`emitTypes()`.
 
-```coffee
-enum Status
-  pending
-  active
-  completed
-  cancelled
+#### 1.1 Lexer: Token Detection
 
-enum HttpCode
-  ok = 200
-  created = 201
-  badRequest = 400
-  notFound = 404
-  serverError = 500
+**Add `::=` and `::` to `OPERATOR_RE`** (in `src/lexer.js`, near line 215).
+
+The current regex:
+
+```js
+let OPERATOR_RE = /^(?:<=>|[-=]>|~>|~=|:=|=!|===|!==|...)/;
 ```
 
-**Emits to both `.js` and `.d.ts`:**
+Add `::=` and `::` with longest-match-first ordering (`::=` before `::`).
+Also note that `IDENTIFIER_RE` already avoids matching `:` when followed by
+`=` or `:` (the `(?![=:])` lookahead), so `::` after an identifier will fall
+through to `literalToken()` where `OPERATOR_RE` picks it up.
 
-```ts
-// .d.ts
-enum Status {
-  pending,
-  active,
-  completed,
-  cancelled
+**Tag the operators** (in the operator tagging section of `literalToken()`,
+near lines 1095-1100, alongside the reactive operators):
+
+```js
+else if (val === '::=') tag = 'TYPE_ALIAS';
+else if (val === '::')  tag = 'TYPE_ANNOTATION';
+```
+
+These must be checked **before** the `([-+:])\1` pattern in the regex, which
+currently matches `::` as a repeated `:`. The `::=` three-character match must
+come first.
+
+#### 1.2 Rewriter: `rewriteTypes()`
+
+**Add the pass to the rewrite pipeline** (in the `rewrite()` method, after
+`rewriteRender()`):
+
+```js
+rewrite(tokens) {
+  this.tokens = tokens;
+  this.removeLeadingNewlines();
+  this.closeOpenCalls();
+  this.closeOpenIndexes();
+  this.normalizeLines();
+  this.rewriteRender();
+  this.rewriteTypes();          // <-- NEW PASS
+  this.tagPostfixConditionals();
+  this.addImplicitBracesAndParens();
+  this.addImplicitCallCommas();
+  return this.tokens;
 }
+```
 
-// .js (runtime object generated)
-const Status = {
-  pending: 0,
-  active: 1,
-  completed: 2,
-  cancelled: 3,
-  0: "pending",
-  1: "active",
-  2: "completed",
-  3: "cancelled"
-};
+**The `rewriteTypes()` method** scans the token stream using `scanTokens()`.
+When it encounters a `TYPE_ANNOTATION` (`::`) token, it:
+
+1. Collects all following tokens that are part of the type expression
+2. Joins them into a type string
+3. Finds the token that survives into the s-expression (see §1.4)
+4. Stores the type string on that token (`.data.type` or `.data.returnType`)
+5. Removes the `::` and collected type tokens from the stream
+
+```js
+rewriteTypes() {
+  this.scanTokens((token, i, tokens) => {
+    let tag = token[0];
+
+    // --- Handle :: (type annotations) ---
+    if (tag === 'TYPE_ANNOTATION') {
+      let prevToken = tokens[i - 1];
+      if (!prevToken) return 1;
+
+      // Collect the type expression
+      let typeTokens = [];
+      let j = i + 1;
+      let depth = 0;
+
+      while (j < tokens.length) {
+        let t = tokens[j];
+        let tTag = t[0];
+
+        // Bracket balancing
+        // NOTE: The lexer tags < and > as 'COMPARE', not '<' or '>'
+        let isOpen = tTag === '(' || tTag === '[' ||
+            tTag === 'CALL_START' || tTag === 'PARAM_START' || tTag === 'INDEX_START' ||
+            (tTag === 'COMPARE' && t[1] === '<');
+        let isClose = tTag === ')' || tTag === ']' ||
+            tTag === 'CALL_END' || tTag === 'PARAM_END' || tTag === 'INDEX_END' ||
+            (tTag === 'COMPARE' && t[1] === '>');
+
+        if (isOpen) {
+          depth++;
+          typeTokens.push(t);
+          j++;
+          continue;
+        }
+        if (isClose) {
+          if (depth > 0) {
+            depth--;
+            typeTokens.push(t);
+            j++;
+            continue;
+          }
+          break;  // Unbalanced close at depth 0 — end of type
+        }
+
+        // Delimiters that end the type at depth 0
+        if (depth === 0) {
+          if (tTag === '=' || tTag === 'REACTIVE_ASSIGN' ||
+              tTag === 'COMPUTED_ASSIGN' || tTag === 'READONLY_ASSIGN' ||
+              tTag === 'REACT_ASSIGN' || tTag === 'TERMINATOR' ||
+              tTag === 'INDENT' || tTag === 'OUTDENT' ||
+              tTag === '->') {                        // code arrow ends type
+            break;
+          }
+          if (tTag === ',') break;
+        }
+
+        // => at depth 0: function type arrow, type continues
+        // -> at depth 0: code arrow, already handled as delimiter above
+        typeTokens.push(t);
+        j++;
+      }
+
+      // Build type string from collected tokens
+      let typeStr = typeTokens.map(t => t[1]).join(' ').replace(/\s+/g, ' ').trim();
+      // Clean up spacing around brackets
+      typeStr = typeStr
+        .replace(/\s*<\s*/g, '<').replace(/\s*>\s*/g, '>')
+        .replace(/\s*\[\s*/g, '[').replace(/\s*\]\s*/g, ']')
+        .replace(/\s*\(\s*/g, '(').replace(/\s*\)\s*/g, ')')
+        .replace(/\s*,\s*/g, ', ');
+
+      // Attach type to the right target token
+      //
+      // IMPORTANT: For return types, the preceding token is CALL_END or
+      // PARAM_END, but the grammar discards these tokens (they don't appear
+      // in s-expressions). Instead, find the token that DOES survive:
+      //   CALL_END → scan backward to function name IDENTIFIER
+      //   PARAM_END → scan forward to the -> token
+      //
+      let target = prevToken;
+      let propName = 'type';
+
+      if (prevToken[0] === 'CALL_END' || prevToken[0] === ')') {
+        // Return type on DEF with parameters.
+        // Scan backward past balanced parens to find function name.
+        let d = 1, k = i - 2;
+        while (k >= 0 && d > 0) {
+          let kTag = tokens[k][0];
+          if (kTag === 'CALL_END' || kTag === ')') d++;
+          if (kTag === 'CALL_START' || kTag === '(') d--;
+          k--;
+        }
+        // k is now at the token before CALL_START — the function name
+        if (k >= 0) target = tokens[k];
+        propName = 'returnType';
+      } else if (prevToken[0] === 'PARAM_END') {
+        // Return type on arrow function: (x:: number):: string -> ...
+        // Scan forward past the type tokens to find the -> token.
+        let arrowIdx = i + 1 + typeTokens.length;
+        let arrowToken = tokens[arrowIdx];
+        if (arrowToken && (arrowToken[0] === '->' || arrowToken[0] === '=>')) {
+          target = arrowToken;
+        }
+        propName = 'returnType';
+      } else if (prevToken[0] === 'IDENTIFIER' && i >= 2 &&
+                 tokens[i - 2]?.[0] === 'DEF') {
+        // Return type on parameterless function: def foo:: string
+        propName = 'returnType';
+      }
+
+      if (!target.data) target.data = {};
+      target.data[propName] = typeStr;
+
+      // Remove :: and type tokens from stream
+      let removeCount = 1 + typeTokens.length;  // :: + type tokens
+      tokens.splice(i, removeCount);
+      return 0;  // Re-examine current position
+    }
+
+    // --- Handle ::= (type aliases) ---
+    // Described in Phase 2 below
+
+    return 1;
+  });
+}
 ```
 
-## When to Use Runtime Enums
+#### 1.3 Type Expression Boundary Detection
+
+The hardest part of type rewriting is determining where a type expression ends.
+The rewriter must **balance brackets** while scanning.
+
+**Delimiters that end a type expression (at bracket depth 0):**
+
+| Token | Why it ends the type |
+|-------|---------------------|
+| `=` `:=` `~=` `=!` `~>` | Assignment operator follows |
+| `->` | Code arrow — function body follows (not part of type) |
+| `TERMINATOR` | End of line |
+| `INDENT` / `OUTDENT` | Block boundary |
+| `)` `CALL_END` `PARAM_END` | End of parameter list |
+| `,` | Next parameter or next item |
+
+**`=>` is NOT a delimiter** — it is the function type arrow. When `=>`
+appears at depth 0 inside a type expression, the type continues (to
+collect the return type). This is why types use `=>` exclusively: it
+disambiguates the function type arrow from the code arrow `->`, which
+always ends a type expression.
+
+**Tokens that adjust bracket depth:**
+
+| Open | Close | Context | Token tag |
+|------|-------|---------|-----------|
+| `<` | `>` | Generic type parameters | `COMPARE` (check `t[1]`) |
+| `(` | `)` | Function type parentheses | `(` / `)` or `CALL_START` / `CALL_END` |
+| `[` | `]` | Array type / index signatures | `[` / `]` or `INDEX_START` / `INDEX_END` |
+
+**Worked examples:**
+
+```
+INPUT:  count:: number = 0
+SCAN:   :: → start collecting
+        number → depth=0, type token
+        = → depth=0, assignment delimiter, STOP
+RESULT: type = "number"
+
+INPUT:  items:: Map<string, number> = x
+SCAN:   :: → start collecting
+        Map → depth=0, type token
+        < → depth=1, type token
+        string → depth=1, type token
+        , → depth=1 (inside <>), type token
+        number → depth=1, type token
+        > → depth=0, type token
+        = → depth=0, assignment delimiter, STOP
+RESULT: type = "Map<string, number>"
+
+INPUT:  def f(a:: number, b:: string)
+SCAN:   :: (after a) → start collecting
+        number → depth=0, type token
+        , → depth=0, parameter delimiter, STOP
+RESULT: type on a = "number"
+SCAN:   :: (after b) → start collecting
+        string → depth=0, type token
+        ) → depth=0, close paren, STOP
+RESULT: type on b = "string"
+
+INPUT:  fn:: (a: number, b: string) => void = ...
+SCAN:   :: → start collecting
+        ( → depth=1, type token
+        a → depth=1, type token
+        : → depth=1, type token
+        number → depth=1, type token
+        , → depth=1 (inside parens), type token
+        b → depth=1, type token
+        : → depth=1, type token
+        string → depth=1, type token
+        ) → depth=0, type token
+        => → depth=0, function type arrow, type token (CONTINUES)
+        void → depth=0, type token
+        = → depth=0, assignment delimiter, STOP
+RESULT: type = "(a: number, b: string) => void"
+
+INPUT:  (name:: string):: string -> "Hello!"
+SCAN:   :: (after PARAM_END) → start collecting return type
+        string → depth=0, type token
+        -> → depth=0, code arrow delimiter, STOP
+RESULT: returnType = "string"
+        -> stays in stream as the function body arrow
+```
+
+**Arrow disambiguation:** Types use `=>` exclusively, code uses `->`.
+This means the rewriter never has to guess what an arrow means during type
+collection — the token itself is the answer:
+
+| Arrow | In type collection | Meaning |
+|-------|-------------------|---------|
+| `=>` | Continue collecting | Function type arrow (part of the type) |
+| `->` | Stop collecting | Code arrow (function body follows) |
+
+**Other special cases:**
+
+- **`?` / `??` / `!` suffixes**: These modify the type. When they appear
+  unspaced after an identifier at depth 0, they are part of the type:
+  `string?` → `"string?"`, `ID!` → `"ID!"`.
+- **Generic `<>` vs comparison**: Inside a type context (after `::`), always
+  treat `<` as opening a generic bracket. The type context is unambiguous
+  because we are already inside a `::` collection.
+
+#### 1.4 Return Type Annotations
+
+Return types appear after the parameter list close:
 
-Use runtime enums only when you need:
+```coffee
+def greet(name:: string):: string
+```
 
-- **Reverse mapping** — Get name from value: `Status[0]` → `"pending"`
-- **Iteration** — Loop over all values at runtime
-- **Explicit numeric values** — `HttpCode.ok === 200`
+After `rewriteTypes()` processes the `::` after `)`, the return type must be
+stored on the **function name IDENTIFIER**, not on `CALL_END`. This is because
+the grammar rule `["def", 2, 4, 6]` discards `CALL_END` (position 5) — any
+data stored there is lost when the parser builds the s-expression.
 
-For all other cases, prefer zero-runtime union types.
+The `rewriteTypes()` code above handles this uniformly — in each case,
+find the token that **survives into the s-expression** and store there:
 
----
+1. **`def` with params** — preceding token is `CALL_END`/`)`: scan **backward**
+   past the balanced parentheses to find the function name IDENTIFIER, store
+   `.data.returnType` there.
+2. **Arrow functions** — preceding token is `PARAM_END`: scan **forward** past
+   the collected type tokens to find the `->` token, store `.data.returnType`
+   there (`->` is the s-expression head: `["->", params, body]`).
+3. **Parameterless `def`** — preceding token is an IDENTIFIER preceded by DEF:
+   store `.data.returnType` directly on the name IDENTIFIER.
 
-# 14. Boundary Validation
+**Property convention:**
+- `.data.type` — variable type, parameter type, property type
+- `.data.returnType` — function/method return type
+- `.data.typeParams` — generic type parameters (`<T, U>`)
 
-## Philosophy
+#### 1.5 Token Flow Examples
 
-Types are compile-time contracts. For data entering your system (user input, API responses, file contents), **validate at boundaries**:
+Each example shows: Rip source → tokens after rewrite → s-expression → outputs.
+
+**Typed variable:**
 
 ```coffee
-# Type declares the shape
-User ::= type
-  id: number
-  name: string
-  email: string
+count:: number = 0
+```
 
-# Validation enforces at runtime
-def parseUser(input:: unknown):: User
-  UserSchema.parse(input)  # Throws if invalid
+Tokens after `rewriteTypes()`:
+```
+IDENTIFIER("count", {type: "number"}), =, NUMBER(0)
 ```
 
-## Recommended Pattern
+S-expression (unchanged from untyped):
+```
+["=", count, 0]         # count carries .data.type = "number"
+```
 
-Use a validation library (like Zod) at IO boundaries:
+.js output (type erased):
+```js
+count = 0
+```
+
+.d.ts output:
+```ts
+let count: number;
+```
+
+**Typed constant:**
 
 ```coffee
-import { z } from "zod"
+MAX:: number =! 100
+```
 
-# Define schema with runtime validation
-UserSchema = z.object
-  id: z.number()
-  name: z.string()
-  email: z.string().email()
+Tokens: `IDENTIFIER("MAX", {type: "number"}), READONLY_ASSIGN, NUMBER(100)`
 
-# Derive type from schema (single source of truth)
-User ::= z.infer<typeof UserSchema>
+S-expression: `["readonly", MAX, 100]` — MAX carries `.data.type = "number"`
 
-# Validate at API boundary
-def createUser(req:: Request):: User
-  data = req.json!
-  UserSchema.parse(data)  # Validates and returns typed data
-```
+.js: `const MAX = 100`
 
-## Trust Internally
+.d.ts: `declare const MAX: number;`
 
-Once data passes boundary validation, trust the types internally:
+**Typed reactive state:**
 
 ```coffee
-def processUser(user:: User):: void
-  # No need to re-validate — type guarantees shape
-  sendWelcomeEmail(user.email)
-  createProfile(user.id, user.name)
+count:: number := 0
+doubled:: number ~= count * 2
 ```
 
----
+S-expressions:
+```
+["state", count, 0]        # count carries .data.type = "number"
+["computed", doubled, ...]  # doubled carries .data.type = "number"
+```
 
-# 15. Implementation Notes
+.d.ts:
+```ts
+declare const count: Signal<number>;
+declare const doubled: Computed<number>;
+```
+
+**Typed function:**
 
-## Parser Changes
+```coffee
+def getUser(id:: number):: User
+  db.find!(id)
+```
+
+Tokens after rewrite:
+```
+DEF, IDENTIFIER("getUser", {returnType: "User"}), CALL_START,
+  IDENTIFIER("id", {type: "number"}),
+CALL_END, INDENT, ..., OUTDENT
+```
 
-The parser must recognize and preserve:
+S-expression: `["def", getUser, [id], body]`
+- `id` carries `.data.type = "number"`
+- `getUser` carries `.data.returnType = "User"`
 
-1. **`::` annotations** — After identifiers, parameters, before return
-2. **`::=` declarations** — Type alias definitions
-3. **Type modifiers** — `?`, `??`, `!` suffixes
-4. **`type` blocks** — Structural type definitions
-5. **Generic syntax** — `<T>`, `<T extends U>`, etc.
-6. **Block unions** — Leading `|` for union members
+.js: `async function getUser(id) { return db.find(id); }`
 
-## AST Representation
+.d.ts: `declare function getUser(id: number): User;`
 
-Type information should be stored as AST metadata:
+**Typed arrow function:**
 
 ```coffee
-# Source
-count:: number = 0
+greet = (name:: string):: string -> "Hello, #{name}!"
 ```
 
-```javascript
-// AST (conceptual)
-["=", "count", 0, { type: "number" }]
+Tokens after rewrite:
+```
+IDENTIFIER("greet"), =, PARAM_START,
+  IDENTIFIER("name", {type: "string"}),
+PARAM_END, ->({returnType: "string"}), ...
 ```
 
-## Code Generation
+**Class properties:**
 
-Type annotations should:
+```coffee
+class UserService
+  db:: Database
+  cache:: Map<string, User>
+```
 
-1. **Strip from runtime** — Never appear in `.js` output
-2. **Preserve for `.d.ts`** — Emit valid TypeScript declarations
-3. **Maintain source order** — Types in `.d.ts` match source file order
+Tokens: identifiers carry `.data.type`, grammar sees normal class body.
 
-## Scope and Validation
+.d.ts:
+```ts
+declare class UserService {
+  db: Database;
+  cache: Map<string, User>;
+}
+```
 
-Rip does **not** need to:
+#### 1.6 Token-Level Type Emission
 
-- Evaluate type expressions
-- Prove type soundness
-- Check type compatibility
-- Resolve type references
+After `rewriteTypes()` strips type annotations and stores metadata on
+tokens, the `emitTypes()` function scans the annotated token stream in a
+single forward pass and emits `.d.ts` declarations. This happens in
+`Compiler.compile()`, between tokenization and parsing — before the
+parser ever sees the tokens.
 
-Rip only needs to:
+`emitTypes()` is a standalone function (not a class). It maintains a
+simple state machine:
 
-- **Parse** type syntax correctly
-- **Preserve** type information in AST
-- **Emit** valid TypeScript type syntax
+- **Indent depth** — tracks INDENT/OUTDENT to know nesting level
+- **Current class** — when inside a CLASS body, emit class members
+- **Export flag** — when EXPORT precedes a declaration, prepend `export`
 
-All actual type checking is delegated to TypeScript when `types: "check"`.
+**Pattern matching** — the function scans forward and recognizes:
 
----
+| Token pattern | Emission |
+|---------------|----------|
+| `DEF IDENTIFIER(+returnType) CALL_START params CALL_END` | `function name(params): ReturnType;` |
+| `DEF IDENTIFIER(+returnType)` (no params) | `function name(): ReturnType;` |
+| `IDENTIFIER(+type) = ...` | `let name: Type;` |
+| `IDENTIFIER(+type) READONLY_ASSIGN ...` | `const name: Type;` |
+| `STATE IDENTIFIER(+type) ...` | `const name: Signal<Type>;` |
+| `COMPUTED IDENTIFIER(+type) ...` | `const name: Computed<Type>;` |
+| `CLASS IDENTIFIER INDENT ... OUTDENT` | `class Name { ... }` |
+| `EXPORT <declaration>` | Prepend `export` to the declaration |
+| `TYPE_DECL` marker | `type Name = TypeText;` or `interface Name { ... }` |
 
-## Summary
+**Rip-to-TypeScript conversions** — `emitTypes()` converts Rip type
+syntax into standard TypeScript:
 
-Rip's optional type system provides:
+| Rip syntax | TypeScript equivalent |
+|-----------|---------------------|
+| `::` | `:` (annotation sigil to type separator) |
+| `T?` | `T \| undefined` |
+| `T??` | `T \| null \| undefined` |
+| `T!` | `NonNullable<T>` |
 
-| Feature | Description |
-|---------|-------------|
-| **Type Annotations** | `::` for variables, parameters, returns |
-| **Type Aliases** | `::=` for named types |
-| **Optionality** | `T?` optional, `T??` nullable, `T!` non-null |
-| **Structural Types** | `type` blocks for object shapes |
-| **Union Types** | Inline or block form with `\|` |
-| **Function Types** | Arrow syntax, overloads supported |
-| **Generics** | Full generic support with constraints |
-| **Adoption Levels** | Project, file, and line granularity |
-| **Emission** | `.js` runtime + `.d.ts` declarations |
+Function type expressions use `=>` directly (same as TypeScript), so no
+arrow conversion is needed.
 
-**The result:**
+The function returns a `.d.ts` string. Declarations without type
+annotations are skipped — only annotated code appears in the output.
 
-- Type-driven development with TypeScript ecosystem compatibility
-- Optional adoption — add types where they help
-- Zero runtime cost — types are compile-time only
-- Minimal syntax — Rip stays Rip
+### Phase 2: Type-Only Declarations
 
-> **Static typing as a discipline, not a mandate.**
+These constructs exist only in the type system — they have no runtime
+representation (except `enum`). The rewriter handles type aliases and
+interfaces entirely (they never enter the grammar). Only `enum` needs a
+grammar rule because it emits runtime JavaScript.
 
----
+#### 2.1 Keyword Migration
 
-# 16. Quick Reference
+**Move `enum` and `interface` from `RESERVED` to `RIP_KEYWORDS`** in
+`src/lexer.js`. Currently (line 83):
 
-## Syntax Cheat Sheet
+```js
+let RESERVED = new Set([
+  'case', 'function', 'var', 'void', 'with', 'const', 'let',
+  'enum', 'native', 'implements', 'interface', 'package',
+  'private', 'protected', 'public', 'static',
+]);
+```
 
-```coffee
-# ═══════════════════════════════════════════════════════════
-# TYPE ANNOTATIONS (::)
-# ═══════════════════════════════════════════════════════════
+Remove `enum` and `interface` from `RESERVED`. Add them to `RIP_KEYWORDS`:
 
-# Variables
-count:: number = 0
-name:: string = "Rip"
-items:: string[] = []
+```js
+let RIP_KEYWORDS = new Set([
+  'undefined', 'Infinity', 'NaN',
+  'then', 'unless', 'until', 'loop', 'of', 'by', 'when', 'def',
+  'component', 'render',
+  'enum', 'interface',          // <-- ADD
+]);
+```
 
-# Constants
-MAX:: number =! 100
+No changes to `classifyKeyword()` are needed — the existing fallback
+`if (RIP_KEYWORDS.has(id)) return upper` (line 618) automatically tags
+`enum` as `ENUM` and `interface` as `INTERFACE`.
 
-# Reactive state
-count:: number := 0
-doubled:: number ~= count * 2
+#### 2.2 Type Aliases (`::=`) — Unified typeText
 
-# Function parameters and return
-def greet(name:: string):: string
-  "Hello, #{name}!"
+The `::=` operator declares a named type. The `rewriteTypes()` pass handles
+it by collecting the right-hand side, converting it to a TypeScript-compatible
+type string, and packaging it into a single `TYPE_DECL` marker token. All
+three forms (simple alias, structural type, block union) produce the same
+metadata shape: `{ name, typeText }`. The `emitTypes()` function simply
+emits `type ${name} = ${typeText};` for all of them.
 
-# ═══════════════════════════════════════════════════════════
-# TYPE ALIASES (::=)
-# ═══════════════════════════════════════════════════════════
+**Simple alias:**
 
-# Simple alias
+```coffee
 ID ::= number
+UserID ::= number | string
+```
 
-# Union (inline)
-Status ::= "pending" | "active" | "done"
+When `rewriteTypes()` encounters `TYPE_ALIAS` (`::=`):
 
-# Union (block - preferred)
-HttpMethod ::=
-  | "GET"
-  | "POST"
-  | "PUT"
-  | "DELETE"
+1. Record the preceding `IDENTIFIER` token as the type name
+2. Collect all following tokens as the type body (same boundary rules as `::`)
+3. Replace the entire sequence (`IDENTIFIER`, `TYPE_ALIAS`, type tokens) with
+   a single `TYPE_DECL` marker token
+
+```js
+// Inside rewriteTypes(), handling TYPE_ALIAS:
+if (tag === 'TYPE_ALIAS') {
+  let nameToken = tokens[i - 1];
+  let name = nameToken[1];
+
+  // Collect type body tokens (same boundary logic as ::)
+  let typeTokens = [];
+  let j = i + 1;
+  let depth = 0;
+  // ... same collection loop as for TYPE_ANNOTATION ...
+
+  let typeStr = /* join collected tokens */;
+
+  // Replace name + ::= + type tokens with TYPE_DECL marker
+  let declToken = gen('TYPE_DECL', name, nameToken);
+  declToken.data = { name, typeText: typeStr };
+  tokens.splice(i - 1, 2 + typeTokens.length, declToken);
+  return 0;
+}
+```
+
+The `TYPE_DECL` marker is read by `emitTypes()` and then **removed from
+the token stream** before parsing. No grammar rule is needed.
+
+.d.ts: `type ID = number;`
+
+.js: *(nothing — type-only, erased)*
+
+**Structural type:**
 
-# Structural type
+```coffee
 User ::= type
   id: number
   name: string
   email?: string
+```
 
-# Function type
-Handler ::= (req:: Request) -> Response
+When `rewriteTypes()` sees `TYPE_ALIAS` followed by `IDENTIFIER("type")` and
+then `INDENT`, it collects the block body and converts it to a TypeScript
+object type string:
 
-# Generic type
-Container<T> ::= type
-  value: T
+1. Consume the `INDENT`
+2. Collect property declarations line by line until `OUTDENT`
+3. Convert to TypeScript object syntax: `"{ id: number; name: string; email?: string; }"`
+4. Store as a single typeText string — no structured property metadata needed:
+   ```js
+   declToken.data = {
+     name: "User",
+     typeText: "{ id: number; name: string; email?: string; }"
+   };
+   ```
+5. Replace entire sequence with single `TYPE_DECL` marker
+
+The rewriter does the Rip-to-TypeScript formatting (indented properties to
+`{ prop: type; ... }`). The emitter just writes `type ${name} = ${typeText};`
+without needing to understand the internal structure.
 
-# ═══════════════════════════════════════════════════════════
-# OPTIONALITY MODIFIERS
-# ═══════════════════════════════════════════════════════════
+.d.ts:
+```ts
+type User = {
+  id: number;
+  name: string;
+  email?: string;
+};
+```
 
-email:: string?        # T | undefined
-middle:: string??      # T | null | undefined
-id:: ID!               # NonNullable<T>
+**Block union:**
 
-# ═══════════════════════════════════════════════════════════
-# GENERICS
-# ═══════════════════════════════════════════════════════════
+```coffee
+HttpMethod ::=
+  | "GET"
+  | "POST"
+  | "PUT"
+  | "DELETE"
+```
 
-def identity<T>(x:: T):: T
-  x
+When `rewriteTypes()` sees `TYPE_ALIAS` followed by `TERMINATOR` or `INDENT`
+with leading `|` tokens, it collects union members and joins them:
 
-def map<T, U>(arr:: T[], fn:: (x:: T) -> U):: U[]
-  arr.map(fn)
+```js
+declToken.data = {
+  name: "HttpMethod",
+  typeText: '"GET" | "POST" | "PUT" | "DELETE"'
+};
+```
 
-# With constraints
-def merge<T extends object>(a:: T, b:: T):: T
-  {...a, ...b}
+.d.ts: `type HttpMethod = "GET" | "POST" | "PUT" | "DELETE";`
 
-# ═══════════════════════════════════════════════════════════
-# INTERFACES
-# ═══════════════════════════════════════════════════════════
+#### 2.3 Interfaces — Rewriter-Based
 
+```coffee
 interface Animal
   name: string
 
 interface Dog extends Animal
   breed: string
+  bark: () => void
+```
+
+Interfaces are type-only (no .js output), so they are handled entirely by
+the rewriter — no grammar rule needed. When `rewriteTypes()` encounters an
+`INTERFACE` token:
+
+1. Record the interface name
+2. If followed by `EXTENDS`, record the parent name
+3. Collect the body block (between `INDENT` and `OUTDENT`)
+4. Convert to TypeScript interface body string
+5. Replace the entire sequence with a `TYPE_DECL` marker:
+   ```js
+   declToken.data = {
+     name: "Dog",
+     kind: "interface",
+     extends: "Animal",
+     typeText: "{ breed: string; bark: () => void; }"
+   };
+   ```
+
+The `emitTypes()` function recognizes kind `"interface"` and emits:
+
+```ts
+interface Dog extends Animal {
+  breed: string;
+  bark: () => void;
+}
+```
+
+The `TYPE_DECL` marker is removed before parsing. The parser and compiler
+never see interfaces.
 
-# ═══════════════════════════════════════════════════════════
-# ENUMS (use sparingly)
-# ═══════════════════════════════════════════════════════════
+.js: *(nothing — erased)*
 
-enum Status
-  pending
-  active
-  done
+#### 2.4 Enums
 
+```coffee
 enum HttpCode
   ok = 200
+  created = 201
   notFound = 404
+  serverError = 500
 ```
 
-## Comparison: Rip vs TypeScript vs CoffeeScript
+Enums are the **one** type construct that emits both .js and .d.ts. They
+are the only construct that needs a grammar rule and a compiler generator.
 
-| Feature | Rip | TypeScript | CoffeeScript |
-|---------|-----|------------|--------------|
-| Type annotations | `x:: T` | `x: T` | N/A |
-| Type aliases | `T ::= ...` | `type T = ...` | N/A |
-| Optional type | `T?` | `T \| undefined` | N/A |
-| Nullable | `T??` | `T \| null \| undefined` | N/A |
-| Non-nullable | `T!` | `NonNullable<T>` | N/A |
-| Structural types | `type` block | `{ ... }` | N/A |
-| Block unions | `\| "a" \| "b"` | Same | N/A |
-| Types required | No | Configurable | N/A |
-| Runtime cost | Zero | Zero | N/A |
+**Grammar rule:**
 
-## Project Configuration
+```
+Enum: [
+  o 'ENUM Identifier Block', '["enum", 2, 3]'
+]
+```
 
-```json
-// package.json
-{
-  "rip": {
-    "types": "emit"   // "off" | "emit" | "check"
+Add `Enum` to the `Expression` list.
+
+S-expression: `["enum", "HttpCode", body]`
+
+.js (runtime reverse-mapping object, via `generateEnum()`):
+```js
+const HttpCode = {
+  ok: 200, created: 201, notFound: 404, serverError: 500,
+  200: "ok", 201: "created", 404: "notFound", 500: "serverError"
+};
+```
+
+.d.ts (emitted by `emitTypes()` from the token stream):
+```ts
+enum HttpCode {
+  ok = 200,
+  created = 201,
+  notFound = 404,
+  serverError = 500
+}
+```
+
+Note: `emitTypes()` reads enum info from the token stream before parsing.
+The enum tokens remain in the stream for the parser (unlike type aliases
+and interfaces, which are removed).
+
+#### 2.5 Grammar Changes Summary
+
+In `src/grammar/grammar.rip`, add `Enum` to the `Expression` list:
+
+```
+Expression: [
+  o 'Value'
+  o 'Code'
+  o 'Operation'
+  o 'Assign'
+  o 'ReactiveAssign'
+  o 'ComputedAssign'
+  o 'ReadonlyAssign'
+  o 'ReactAssign'
+  o 'Enum'                 # <-- ADD (only type construct needing grammar)
+  o 'If'
+  ...
+]
+```
+
+And add the single new rule:
+
+```
+Enum: [
+  o 'ENUM Identifier Block', '["enum", 2, 3]'
+]
+```
+
+Also add to `Export`:
+
+```
+o 'EXPORT Enum'        , '["export", 2]'
+```
+
+No `TypeDecl` or `Interface` grammar rules — those are handled entirely by
+the rewriter and removed before parsing.
+
+#### 2.6 Generic Type Parameters
+
+```coffee
+def identity<T>(value:: T):: T
+  value
+
+def map<T, U>(items:: T[], fn:: (item:: T) => U):: U[]
+  items.map(fn)
+```
+
+Generic parameters on functions require special handling because `<` is
+normally a comparison operator.
+
+**Detection via `.spaced` property:**
+
+The lexer tracks whitespace before every token via the `.spaced` property.
+In `def identity<T>`, the `<` token is unspaced from the identifier — this
+is the key signal. In a comparison `x < y`, the `<` is spaced.
+
+When `rewriteTypes()` sees `DEF IDENTIFIER` followed by an unspaced `<`:
+
+1. Treat it as a generic parameter list
+2. Collect balanced `<...>` tokens as a string (e.g., `"<T>"`, `"<T, U>"`,
+   `"<T extends Ordered>"`)
+3. Store on the function name token as `.data.typeParams`
+4. Remove the `<...>` tokens from the stream
+
+```js
+// Generic detection using .spaced:
+if (tag === 'IDENTIFIER' && i >= 1 && tokens[i - 1]?.[0] === 'DEF') {
+  let next = tokens[i + 1];
+  if (next && next[0] === 'COMPARE' && next[1] === '<' && !next.spaced) {
+    let genTokens = collectBalancedAngleBrackets(tokens, i + 1);
+    if (genTokens) {
+      if (!token.data) token.data = {};
+      token.data.typeParams = joinTokens(genTokens);
+      tokens.splice(i + 1, genTokens.length);
+    }
   }
 }
 ```
 
-## File Directives
+Generic parameters on type aliases work the same way:
 
 ```coffee
-# @types off    — Ignore types in this file
-# @types emit   — Parse and emit .d.ts
-# @types check  — Full TypeScript checking
+Container<T> ::= type
+  value: T
+```
+
+The `rewriteTypes()` pass detects `IDENTIFIER` + unspaced `<...>` +
+`TYPE_ALIAS` and collects the generic params before processing the `::=`.
+
+.d.ts:
+```ts
+function identity<T>(value: T): T;
+function map<T, U>(items: T[], fn: (item: T) => U): U[];
+type Container<T> = { value: T; };
+```
+
+### Phase 3: Dual Emission (.js and .d.ts)
+
+All type-related logic lives in `src/types.js`. The `.d.ts` is emitted from
+the annotated token stream (before parsing). The `.js` is generated by the
+existing CodeGenerator (after parsing), with only `generateEnum()` added.
+
+#### 3.1 `generateEnum()` — The One Compiler Addition
+
+Enums are the only type construct that produces runtime JavaScript. The
+`generateEnum()` function is exported from `types.js` and wired onto the
+CodeGenerator prototype:
+
+```js
+// In src/types.js
+export function generateEnum(head, rest, context) {
+  let [name, body] = rest;
+  // Parse body into key-value pairs
+  let pairs = this.parseEnumBody(body);
+  let forward = pairs.map(([k, v]) => `${k}: ${v}`).join(', ');
+  let reverse = pairs.map(([k, v]) => `${v}: "${k}"`).join(', ');
+  return `const ${name} = {${forward}, ${reverse}}`;
+}
+```
+
+**Wiring in `src/compiler.js`:**
+
+```js
+import { emitTypes, generateEnum } from './types.js';
+CodeGenerator.prototype.generateEnum = generateEnum;
+CodeGenerator.GENERATORS['enum'] = 'generateEnum';
 ```
 
+No `generateTypeAlias()` or `generateInterface()` methods are needed —
+type aliases and interfaces are removed from the token stream by the
+rewriter before the parser ever sees them.
+
+#### 3.2 `emitTypes()` — Token-Level .d.ts Emission
+
+The `emitTypes()` function replaces the `DtsGenerator` class. Instead of
+walking the s-expression tree, it scans the annotated token stream in a
+single forward pass. This is simpler because:
+
+- It doesn't duplicate the CodeGenerator's dispatch logic
+- It only handles declarations (not all AST node types)
+- It reads metadata that `rewriteTypes()` already placed on tokens
+
+See §1.6 for the pattern-matching table and state machine description.
+
+#### 3.3 Compiler Wiring
+
+In `src/compiler.js`, the compilation pipeline becomes:
+
+```js
+compile(source) {
+  // Step 1: Tokenize (includes rewriteTypes() via installTypeSupport)
+  let lexer = new Lexer();
+  let tokens = lexer.tokenize(source);
+
+  // Step 2: Emit .d.ts from annotated tokens (before parsing)
+  let dts = null;
+  if (this.options.types === 'emit' || this.options.types === 'check') {
+    dts = emitTypes(tokens);
+    // Remove TYPE_DECL markers so the parser doesn't see them
+    tokens = tokens.filter(t => t[0] !== 'TYPE_DECL');
+  }
+
+  // Step 3: Parse (grammar only sees Enum as a new construct)
+  // ... existing parser setup ...
+  let sexpr = parser.parse(source);
+
+  // Step 4: Generate .js (CodeGenerator only needs generateEnum)
+  let generator = new CodeGenerator({ ... });
+  let code = generator.compile(sexpr);
+
+  return { tokens, sexpr, code, dts, data: dataSection, reactiveVars: generator.reactiveVars };
+}
+```
+
+The key insight: `.d.ts` emission happens **between tokenization and
+parsing**. After `emitTypes()` reads the annotated tokens, `TYPE_DECL`
+markers are filtered out. The parser receives a clean, type-free token
+stream — identical to what it would see from untyped Rip code, plus
+`ENUM` tokens.
+
+#### 3.4 `const` Emission Rule
+
+Type annotations never affect `let` vs `const` in `.js` output:
+
+| Rip operator | .js keyword | .d.ts keyword |
+|-------------|-------------|---------------|
+| `=` | `let` (hoisted by `programVars`) | `let` |
+| `=!` | `const` | `const` |
+| `:=` | `const` (reactive signal) | `const` (Signal) |
+| `~=` | `const` (computed signal) | `const` (Computed) |
+| `~>` | `const` (effect) | `const` |
+
+### Edge Cases
+
+#### Optionality Suffixes in Types
+
+The `?`, `??`, and `!` suffixes appear unspaced after the type name:
+
+```coffee
+email:: string?       # → type = "string?"
+middle:: string??     # → type = "string??"
+id:: ID!              # → type = "ID!"
+```
+
+In `rewriteTypes()`, when collecting type tokens, if the next token is `?`,
+`??`, or `!` and is **not spaced** from the previous token, include it as
+part of the type string.
+
+The `emitTypes()` function expands these suffixes into standard TypeScript:
+
+| Rip suffix | TypeScript equivalent |
+|-----------|---------------------|
+| `T?` | `T \| undefined` |
+| `T??` | `T \| null \| undefined` |
+| `T!` | `NonNullable<T>` |
+
+See §1.6 for the full Rip-to-TypeScript conversion table (including `::` → `:`).
+
+#### File-Level Type Directives
+
+```coffee
+# @types off     — ignore types in this file
+# @types emit    — emit .d.ts
+# @types check   — emit .d.ts + enable tsc validation
+```
+
+These are comments. The lexer's `commentToken()` method can detect this
+pattern and set a flag. Alternatively, the `Compiler` can scan for the
+directive before tokenizing.
+
+#### Export of Type-Only Declarations
+
+```coffee
+export User ::= type
+  id: number
+  name: string
+
+export def getUser(id:: number):: User?
+  db.find(id)
+```
+
+The rewriter detects `EXPORT` before `::=` sequences and marks the
+`TYPE_DECL` marker accordingly. The `emitTypes()` function prepends
+`export` to the declaration. No grammar rule is involved for type-only
+exports — the `TYPE_DECL` marker is removed before parsing.
+
+For exported functions, the existing `Export` grammar rules handle
+`EXPORT Expression` as before.
+
+.js (type alias erased, function exported):
+```js
+export function getUser(id) {
+  return db.find(id);
+}
+```
+
+.d.ts (both exported):
+```ts
+export type User = { id: number; name: string; };
+export function getUser(id: number): User | undefined;
+```
+
+### Test Matrix
+
+Each row is a test case. Verify both .js and .d.ts output.
+
+| # | Rip Input | .js Output | .d.ts Output |
+|---|-----------|-----------|-------------|
+| 1 | `count:: number = 0` | `count = 0` | `let count: number;` |
+| 2 | `MAX:: number =! 100` | `const MAX = 100` | `declare const MAX: number;` |
+| 3 | `count:: number := 0` | `const count = __state(0)` | `declare const count: Signal<number>;` |
+| 4 | `doubled:: number ~= x * 2` | `const doubled = __computed(...)` | `declare const doubled: Computed<number>;` |
+| 5 | `def f(a:: number):: string` | `function f(a) { ... }` | `declare function f(a: number): string;` |
+| 6 | `(x:: number):: number -> x + 1` | `(x) => x + 1` | `(x: number) => number` |
+| 7 | `ID ::= number` | *(empty)* | `type ID = number;` |
+| 8 | `User ::= type` (+ block) | *(empty)* | `type User = { id: number; ... };` |
+| 9 | `Status ::= \| "a" \| "b"` | *(empty)* | `type Status = "a" \| "b";` |
+| 10 | `interface Foo` (+ block) | *(empty)* | `interface Foo { ... }` |
+| 11 | `enum Code` (+ block) | `const Code = { ... }` | `enum Code { ... }` |
+| 12 | `items:: Map<string, number> = x` | `items = x` | `let items: Map<string, number>;` |
+| 13 | `email:: string?` | — | `let email: string \| undefined;` |
+| 14 | `id:: ID!` | — | `let id: NonNullable<ID>;` |
+| 15 | `def identity<T>(v:: T):: T` | `function identity(v) { ... }` | `declare function identity<T>(v: T): T;` |
+| 16 | `export User ::= type` (+ block) | *(empty)* | `export type User = { ... };` |
+| 17 | `export def f(x:: number):: number` | `export function f(x) { ... }` | `export function f(x: number): number;` |
+
 ---
 
 **See Also:**