rip-lang 3.17.3 → 3.17.5

package/README.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/shreeve/rip-lang/commits/main"><img src="https://img.shields.io/badge/version-3.17.3-blue.svg" alt="Version"></a>
+  <a href="https://github.com/shreeve/rip-lang/commits/main"><img src="https://img.shields.io/badge/version-3.17.5-blue.svg" alt="Version"></a>
   <a href="#zero-dependencies"><img src="https://img.shields.io/badge/dependencies-ZERO-brightgreen.svg" alt="Dependencies"></a>
   <a href="#"><img src="https://img.shields.io/badge/tests-1%2C436%2F1%2C436-brightgreen.svg" alt="Tests"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License"></a>

package/docs/RIP-LANG.md

@@ -343,6 +343,7 @@ Multiple lines
 | `?!` | Presence | `@checked?!` | `(this.checked ? true : undefined)` — Houdini operator |
 | `=~` | Match | `str =~ /pat/` | Ruby-style regex match, captures in `_` |
 | `::` | Prototype | `String::trim` | `String.prototype.trim` |
+| `as` | Type cast | `x as Foo` | Type-checker-only assertion — erased at runtime |
 | `[-n]` | Negative index | `arr[-1]` | `arr.at(-1)` |
 | `*` | String repeat | `"-" * 40` | `"-".repeat(40)` |
 | `<` `<=` | Chained comparison | `1 < x < 10` | `(1 < x) && (x < 10)` |
@@ -884,6 +885,23 @@ Rip's reactive features are **language-level operators**, not library imports.
 | `<~` | Render-ready | "loads from" | Server-backed state, loaded before render (component bodies) |
 | `=!` | Readonly | "equals, dammit!" | Constant (`const`) |
 
+### Uniform meaning — including component members
+
+The declaration operators mean the **same thing everywhere**, and that includes members declared inside a `component` body:
+
+| Operator | In a component, a member declared with it is… |
+|----------|-----------------------------------------------|
+| `x = v`  | a **plain, non-reactive** field — `this.x = v`. Reads/writes are ordinary property access; the UI does **not** re-render when it changes. |
+| `x := v` | **reactive state** — `this.x = __state(v)`. Reads/writes flow through the signal and re-render dependents. |
+| `x =! v` | a readonly **const** field. |
+| `x ~= e` | a **computed**; `x ~> …` an **effect**; `x: -> …` (or `x = -> …`) a **method**. |
+
+A plain `=` member is **not** a reactive member and is **not** a valid `ref:` target — `ref:` still requires a `:=` state cell.
+
+**Props.** `@`-prefixed reactive props are declared with `@name :=` (or bare `@name` for a required prop) so that a parent updating the prop re-renders the child. `@name = v` is a *plain public field*: its initial value is read once from props and it is non-reactive (rare — prefer `:=` unless you specifically want a one-time prop snapshot).
+
+**Silent-freeze diagnostic.** Because a `=` member is non-reactive, the compiler raises an error if a private `=` member is **read** in `render` / a `~=` computed / a `~>` effect **and reassigned** somewhere in the component — that combination would read the value once and silently never update. The fix is to declare it with `:=`.
+
 ## Reactive Behavior
 
 |  | `:=` state | `~=` computed | `~>` effect |
@@ -1107,6 +1125,47 @@ declare const count: Signal<number>;
 declare const doubled: Computed<number>;
 ```
 
+## Type Cast (`expr as Type`)
+
+`expr as Type` is a TypeScript-style cast. It is **purely a type-checker
+construct**: it is **erased at runtime** (the emitted JavaScript is exactly
+`expr`, with no trace of the cast) and only feeds the shadow-TS type checker,
+where it asserts/narrows the value's type. The grammar **never parses a type** —
+the type rewriter collapses the `as Type` run into a single opaque-string marker
+token, and the grammar reduces a structural postfix node (`['cast', expr,
+typeStr]`), conceptually like `!` or `?.`. So no type syntax ever reaches the
+parser.
+
+```coffee
+y = x as Foo                       # runtime: y = x ; checker: y is Foo
+m = x as Map<string, number>       # generics, unions (A | B), intersections,
+u = x as A | B                     #   object/array types are all accepted
+chained = x as A as B              # chaining works (left-associative)
+style = el.style as unknown as Record<string, string>   # via `unknown`
+```
+
+It is **not** a cast in `for x as iter`, `for x as! iter`, `import x as y`,
+`export x as y`, or after `.`/`?.` (`obj.as` is a property) — those keep their
+existing meaning.
+
+**Narrowing — every expression form.** Because the cast is a grammar node that
+reduces *after* the full postfix expression is built, it narrows for the checker
+on **all** carriers — identifier, member access, and call / index /
+parenthesized results alike:
+
+```coffee
+v = raw as Aug          # ✅ narrows  (identifier)
+v = obj.prop as Aug     # ✅ narrows  (member access)
+v = foo() as Aug        # ✅ narrows  (call result)
+v = arr[0] as Aug       # ✅ narrows  (index result)
+v = (raw) as Aug        # ✅ narrows  (parenthesized)
+```
+
+**Precedence** matches TypeScript: `as` binds looser than member/call/index and
+arithmetic (`a + b as T` is `(a + b) as T`) but tighter than relational and
+comparison operators, and chains are left-associative (`x as A as B` is
+`(x as A) as B`).
+
 ## Two-Way Binding (`<=>`)
 
 The `<=>` operator creates bidirectional reactive bindings inside render blocks.
@@ -1612,6 +1671,14 @@ App = component
   ~> p "count is now #{count}"    # re-runs when count changes
 ```
 
+**Declaration order (convention):** order the top-of-component block as
+props → locals → refs, separated by one blank line. Within the locals
+group the sub-order is `:=` → `=` → `=!` → `~=` → `~>`. Because `:=`
+(reactive state) and `=` (plain non-reactive field) are semantically
+distinct, keep them grouped separately — all reactive state first, then
+plain mutable fields — never interleaved. The `Ref`-suffix `:=` cells
+used as `ref:` targets go in the final group.
+
 **Render Blocks — Template Syntax:**
 
 ```coffee
@@ -1630,9 +1697,12 @@ App = component
         "Click me"
 ```
 
-**Auto-Wired Event Handlers:**
+**Event Directives:**
 
-Methods named `on` + capitalized event name are automatically bound to the component's root element:
+Events bind on the element where you declare them — never by method name alone.
+A bare `@click` is shorthand for `@click: @onClick`: it resolves to a component
+method named `on` + the capitalized event (`@click` → `onClick`, `@keydown` →
+`onKeydown`), bound to that element:
 
 ```coffee
 Checkbox = component
@@ -1644,10 +1714,27 @@ Checkbox = component
       @onClick()
   render
     button role: 'checkbox', aria-checked: !!@checked
+      @click          # binds onClick to this button
+      @keydown        # binds onKeydown
       slot
 ```
 
-The compiler wires `addEventListener('click', ...)` and `addEventListener('keydown', ...)` to the root `button`. To override for a specific event, write an explicit binding on the root: `button @click: someOtherHandler`. Lifecycle hooks (`onError`) are not auto-wired.
+The bare form works on the tag-head line (`button @click`) or on its own line in
+the element's body. For a handler whose name doesn't match the event — or any
+inline/expression handler — use the explicit form, which accepts any expression:
+
+```coffee
+button @click: someOtherHandler
+button @keydown: @onTriggerKeydown
+button @click: (e) -> e.stopPropagation()
+```
+
+Defining `onClick` alone attaches nothing — the listener exists only where the
+template declares `@click`, so it's always visible exactly where it fires. A bare
+`@<name>` that isn't a real DOM event is a compile error (use `= @name` or
+`"#{@name}"` to render a member as text); bare `@error` is rejected because it
+collides with the `onError` lifecycle hook (write `@error: handler` for a DOM
+error listener).
 
 **Conditional Rendering:**
 

package/docs/RIP-TYPES.md

@@ -631,6 +631,39 @@ Configure via the `"rip"` key in `package.json`:
 | `strict` | Enable TS strict family for `rip check` (default: `false`) |
 | `checkAll` | Type-check every non-`@nocheck` `.rip` file, not just annotated ones (default: `false`) |
 | `exclude` | Glob patterns for files to skip during `rip check` |
+| `types` | Extra hand-written ambient `.d.ts` files to include as explicit program roots (paths relative to the project root). The **escape hatch** for ad-hoc / non-dependency `.d.ts` — most dependency-provided ambients arrive automatically (see below). A missing path is warned and skipped, not fatal. |
+| `ambient` | Declared **by a package** (not a consumer): the ambient `.d.ts` files this package ships, so consumers that depend on it get them automatically. Paths are relative to the package root; the file must also be in `files`. |
+
+### Ambient `.d.ts` includes — two mechanisms
+
+A `.d.ts` added as an explicit program root contributes its global `declare`s to
+every `.rip` file in the project — like tsconfig's `files`, and unlike the `types`
+compiler option it is **not** suppressed by the auto-discovered `@types/*` set.
+Rip feeds that list from two places:
+
+1. **Automatic (`rip.ambient`, zero-config).** A package advertises the ambient
+   types it ships via its own `package.json#rip.ambient`. Any project that
+   declares that package as a dependency (`dependencies`, `devDependencies`,
+   `peerDependencies`, or `optionalDependencies`) auto-includes those files
+   during `rip check` — resolved relative to the dependency's installed location.
+   "You used the framework, so its types are just there."
+
+   For example, `@rip-lang/app` ships `aria.d.ts` for the global `ARIA` helpers:
+
+   ```json
+   { "name": "@rip-lang/app", "rip": { "ambient": ["aria.d.ts"] }, "files": ["index.rip", "aria.d.ts"] }
+   ```
+
+   So an app or package that depends on `@rip-lang/app` gets `ARIA` typed with no
+   configuration at all.
+
+2. **Explicit (`rip.types`, escape hatch).** Point at any `.d.ts` by path
+   (relative to the project root) — for ad-hoc declarations or a `.d.ts` that
+   isn't shipped by a dependency.
+
+Both feeds are merged and **deduped by absolute path**, so pointing `rip.types`
+at a file a dependency already provides is harmless. Missing/unresolvable entries
+are warned and skipped, never fatal.
 
 ### File Level
 

package/docs/demo/routes/card.rip

@@ -7,4 +7,4 @@ export Card = component
     div.card
       if title
         h3 "#{title}"
-      @children
+      slot