rip-lang 3.16.0 → 3.16.1

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.16.0-blue.svg" alt="Version"></a>
+  <a href="https://github.com/shreeve/rip-lang/commits/main"><img src="https://img.shields.io/badge/version-3.16.1-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/bin/rip

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 
-import { readFileSync, readdirSync, writeFileSync, existsSync, statSync, unlinkSync } from 'fs';
+import { readFileSync, readdirSync, writeFileSync, existsSync, statSync, unlinkSync, lstatSync, readlinkSync, rmSync, mkdirSync, symlinkSync, realpathSync } from 'fs';
 import { execSync, spawnSync, spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 import { dirname, basename, join } from 'path';
@@ -60,7 +60,12 @@ Options:
 
 Subcommands:
   rip check [dir]               Type-check all .rip files in directory
-  rip check --strict [dir]      Require type annotations in all .rip files
+  rip check --audit [pkgDir]    Audit a typed package's public API surface for 'any' leaks
+  rip check --sourcemap [dir]   Verify source-map round-trip for every identifier
+                                (hover/go-to-def integrity). Useful for compiler work.
+  rip link [--quiet]            After 'bun install', symlink @rip-lang/* deps to
+                                local source (opt-in, for framework devs;
+                                undo with 'bun install --force')
   rip <name> [args]             Run rip-<name> (repo bin/, node_modules, or PATH)
 
   Configure via rip.json or package.json:
@@ -95,6 +100,121 @@ Shebang support:
 `);
 }
 
+// `rip link` — opt-in override for framework maintainers, layered on top of a
+// normal install. The canonical setup for any rip project is `bun install`
+// (published packages, lockfile, transitive deps); `rip link` then redirects
+// the @rip-lang/* deps to this CLI's own source checkout, by symlinking them
+// into ./node_modules/@rip-lang/* (plus matching .bin shims). The `rip-lang`
+// compiler/toolchain is pointed at source too, so the loader and VS Code LSP
+// load the matching toolchain instead of a shadowing published tarball. Lets
+// you edit framework source live without publishing.
+//
+// Requires `bun install` first — it overrides an existing install, it is not a
+// substitute for one. Reversible: the symlinks live in node_modules (gitignored)
+// and package.json stays clean semver, so `bun install --force` restores the
+// published packages (a plain `bun install` sees the lockfile as satisfied and
+// leaves the symlinks in place). No-op when no source tree is found (e.g. `rip`
+// installed from npm without a dev checkout) — projects then just use installed
+// packages.
+//
+// Source is this CLI's repo root (so it Just Works after `link-global`),
+// overridable via RIP_SRC.
+function ripLink(args) {
+  const quiet = args.includes('--quiet');
+  const log = (msg) => { if (!quiet) console.log(`[rip] link: ${msg}`); };
+
+  const rawSrc = process.env.RIP_SRC || join(__dirname, '..');
+  if (!existsSync(join(rawSrc, 'packages'))) {
+    log(`no rip-lang source at ${rawSrc} — using installed packages (set RIP_SRC to override)`);
+    return;
+  }
+  const src = realpathSync(rawSrc);
+
+  const cwd = process.cwd();
+  const pkgPath = join(cwd, 'package.json');
+  if (!existsSync(pkgPath)) {
+    console.error('[rip] link: no package.json in current directory');
+    process.exit(1);
+  }
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+  const deps = Object.keys(pkg.dependencies || {}).filter((d) => d.startsWith('@rip-lang/'));
+  if (deps.length === 0) {
+    log('no @rip-lang/* dependencies declared — nothing to link');
+    return;
+  }
+
+  const nodeModules = join(cwd, 'node_modules');
+  if (!existsSync(nodeModules)) {
+    console.error('[rip] link: no node_modules found — run `bun install` first, then `rip link`.');
+    process.exit(1);
+  }
+  const binDir = join(nodeModules, '.bin');
+
+  const linkTo = (path, target, type = 'dir') => {
+    try {
+      if (lstatSync(path).isSymbolicLink() && readlinkSync(path) === target) return false;
+      rmSync(path, { recursive: true, force: true });
+    } catch {}
+    mkdirSync(dirname(path), { recursive: true });
+    symlinkSync(target, path, type);
+    return true;
+  };
+
+  const linked = [];   // { dep, bins: [names] } for each resolved package
+  let changed = false;
+
+  for (const dep of deps) {
+    const short = dep.slice('@rip-lang/'.length);
+    const target = join(src, 'packages', short);
+    if (!existsSync(target)) { log(`skip ${dep} — not found at ${target}`); continue; }
+    if (linkTo(join(nodeModules, '@rip-lang', short), target)) changed = true;
+
+    // Re-create .bin shims from the package's own `bin` field so `rip server`
+    // and friends resolve source binaries from this project's node_modules.
+    let meta = {};
+    try { meta = JSON.parse(readFileSync(join(target, 'package.json'), 'utf-8')); } catch {}
+    const binMap = typeof meta.bin === 'string' ? { [short]: meta.bin } : (meta.bin || {});
+    const bins = [];
+    for (const [name, rel] of Object.entries(binMap)) {
+      const binTarget = join(target, rel);
+      if (!existsSync(binTarget)) continue;
+      if (linkTo(join(binDir, name), binTarget, 'file')) changed = true;
+      bins.push(name);
+    }
+    linked.push({ dep, bins });
+  }
+
+  // The compiler/toolchain itself. Every @rip-lang/* package depends on it,
+  // and the loader + VS Code LSP resolve it from the project's node_modules —
+  // so it must point at source too, otherwise a published `rip-lang` tarball
+  // shadows it (e.g. the LSP loading a typecheck.js without the latest API).
+  if (existsSync(join(nodeModules, 'rip-lang'))) {
+    if (linkTo(join(nodeModules, 'rip-lang'), src)) changed = true;
+    linked.push({ dep: 'rip-lang', bins: [], label: 'compiler' });
+  }
+
+  if (quiet || linked.length === 0) {
+    if (linked.length === 0) log('no @rip-lang/* packages resolved to source');
+    return;
+  }
+
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+  const tilde = (p) => home && p.startsWith(home) ? '~' + p.slice(home.length) : p;
+  const tty = process.stdout.isTTY;
+  const dim = (s) => tty ? `\x1b[2m${s}\x1b[0m` : s;
+  const bold = (s) => tty ? `\x1b[1m${s}\x1b[0m` : s;
+
+  const n = linked.length;
+  const verb = changed ? 'linked' : 'already linked';
+  console.log(`${bold('rip link')} ${dim('·')} ${verb} ${n} package${n === 1 ? '' : 's'} ${dim('→ ' + tilde(src))}`);
+  const width = Math.max(...linked.map((l) => l.dep.length));
+  for (const { dep, bins, label } of linked) {
+    const tag = label || (bins.length ? `bin: ${bins.join(', ')}` : '');
+    const line = tag ? `${dep.padEnd(width)}${dim(`  ${tag}`)}` : dep;
+    console.log(`  ${dim('•')} ${line}`);
+  }
+}
+
 async function main() {
   const args = process.argv.slice(2);
 
@@ -140,14 +260,27 @@ async function main() {
   // --- Built-in subcommands ---
 
   if (args[0] === 'check') {
-    const { runCheck } = await import('../src/typecheck.js');
     const checkArgs = args.slice(1);
+    const VALID_FLAGS = new Set(['--audit', '--sourcemap']);
+    const unknown = checkArgs.filter(a => a.startsWith('-') && !VALID_FLAGS.has(a));
+    if (unknown.length > 0) {
+      console.error(`rip check: unknown flag${unknown.length === 1 ? '' : 's'}: ${unknown.join(', ')}`);
+      console.error(`Valid flags: ${[...VALID_FLAGS].join(', ')}`);
+      process.exit(2);
+    }
     const dir = checkArgs.find(a => !a.startsWith('-')) || '.';
-    const exitCode = await runCheck(dir, {
-      quiet: checkArgs.includes('-q') || checkArgs.includes('--quiet'),
-      strict: checkArgs.includes('--strict'),
-    });
-    process.exit(exitCode);
+    const wantAudit     = checkArgs.includes('--audit');
+    const wantSourcemap = checkArgs.includes('--sourcemap');
+    const { runCheck, runAudit } = await import('../src/typecheck.js');
+    const checkCode = await runCheck(dir, { sourceMapAudit: wantSourcemap });
+    if (!wantAudit) process.exit(checkCode);
+    const auditCode = await runAudit(dir);
+    process.exit(checkCode || auditCode);
+  }
+
+  if (args[0] === 'link') {
+    ripLink(args.slice(1));
+    process.exit(0);
   }
 
   // --- Subcommand dispatch: rip <name> → rip-<name> ---
@@ -197,13 +330,32 @@ async function main() {
         }
       }
 
-      // 5. Global PATH: rip-<name>
+      // 5. Nearest node_modules/.bin walking up from the cwd. `getRepoRoot`
+      // uses `git rev-parse --show-toplevel`, which returns the OUTERMOST git
+      // repo — wrong when a project lives in a subdirectory of a larger git
+      // repo: step 4 then probes the outer repo's node_modules and misses the
+      // project's own declared bins. Resolve the bin the way Node resolves a
+      // dependency — nearest node_modules up the tree from the cwd — which is
+      // correct for nested projects and standalone consumers alike.
+      let nmDir = process.cwd();
+      while (true) {
+        const nmBin = join(nmDir, 'node_modules', '.bin', `rip-${name}`);
+        if (existsSync(nmBin)) {
+          const r = spawnSync(nmBin, subArgs, { stdio: 'inherit', env: process.env });
+          process.exit(r.status ?? 1);
+        }
+        const parent = dirname(nmDir);
+        if (parent === nmDir) break;
+        nmDir = parent;
+      }
+
+      // 6. Global PATH: rip-<name>
       const pathResult = spawnSync(`rip-${name}`, subArgs, { stdio: 'inherit', env: process.env });
       if (pathResult.error?.code !== 'ENOENT') {
         process.exit(pathResult.status ?? 1);
       }
 
-      // 6. Not found
+      // 7. Not found
       console.error(`rip: unknown command '${name}'\n\nRun 'rip --help' for usage.`);
       process.exit(1);
     }

package/docs/AGENTS.md

@@ -38,6 +38,6 @@ App.mount()
 - `demo.html` and `charts.html` — dashboard demos
 - `sierpinski.html` — CDN demo
 - `example/index.html` and `results/index.html` — app launchers / examples. `example/index.json` is generated from `docs/demo/` via `bun run bundle:demo` (the source-of-truth lives in `docs/demo/`, the JSON is the deployable artifact).
-- `ui/index.html` — widget gallery. `ui/bundle.json` is generated from `packages/ui/browser/components/` via `bun run bundle:ui` (auto-runs as part of `bun run build`). The source-of-truth is the workspace package; the JSON is the deployable artifact. The gallery loads the bundle at boot via `data-src="bundle.json"` and reads view-source text synchronously from the in-memory components store (`window.__RIP__.components.read("components/<id>.rip")`) — no per-component fetches.
+- `ui/index.html` — widget gallery. `ui/bundle.json` is generated from `packages/ui/browser/components/` via `bun run bundle:ui` (auto-runs as part of `bun run build`). The source-of-truth is the workspace package; the JSON is the deployable artifact. The gallery loads the bundle at boot via `data-src="bundle.json"` and reads view-source text synchronously from the in-memory components store (`window.__RIP__.components.read("_pkg/ui/<id>.rip")`) — no per-component fetches.
 
 Static demos can be opened via `file://`. The playground and example app require `bun run serve`.

package/docs/RIP-APP.md

@@ -24,21 +24,37 @@ shaped the way it is, and how to use it well.
 
 # Contents
 
-1. [The four-layer architecture](#1-the-four-layer-architecture)
-2. [Quick start — the 30-second wow](#2-quick-start)
-3. [The subsystems](#3-the-subsystems)
-   - [Stash](#stash)
-   - [createResource](#createresource)
-   - [Timing helpers](#timing-helpers)
-   - [Components store](#components-store)
-   - [createRouter](#createrouter)
-   - [createRenderer](#createrenderer)
-   - [launch](#launch)
-   - [ARIA helpers](#aria-helpers)
-4. [Lifecycle invariants — what fires when, what owns what](#4-lifecycle-invariants)
-5. [Async effects — `getEffectSignal` and cancellation](#5-async-effects)
-6. [Gotchas — things that have bitten us before](#6-gotchas)
-7. [When NOT to use Rip App](#7-when-not-to-use)
+- [Rip App — Application Framework](#rip-app--application-framework)
+- [Contents](#contents)
+  - [1. The four-layer architecture](#1-the-four-layer-architecture)
+  - [2. Quick start](#2-quick-start)
+    - [Real apps: bundles + file-based routing](#real-apps-bundles--file-based-routing)
+  - [3. The subsystems](#3-the-subsystems)
+    - [Stash](#stash)
+    - [createResource](#createresource)
+    - [Timing helpers](#timing-helpers)
+    - [Components store](#components-store)
+    - [createRouter](#createrouter)
+    - [createRenderer](#createrenderer)
+    - [launch](#launch)
+    - [ARIA helpers](#aria-helpers)
+  - [4. Lifecycle invariants](#4-lifecycle-invariants)
+    - [Component lifecycle order](#component-lifecycle-order)
+    - [User hooks](#user-hooks)
+    - [Effect ownership](#effect-ownership)
+    - [Effect cleanup-on-rerun](#effect-cleanup-on-rerun)
+    - [Parent chain (for context)](#parent-chain-for-context)
+    - [Layout and page parentage](#layout-and-page-parentage)
+    - [Factory blocks (for/if in render)](#factory-blocks-forif-in-render)
+    - [Keyed list reconciliation](#keyed-list-reconciliation)
+  - [5. Async effects](#5-async-effects)
+  - [6. Gotchas](#6-gotchas)
+    - [The bundle boundary matters](#the-bundle-boundary-matters)
+    - [Render-template name shadowing (fixed)](#render-template-name-shadowing-fixed)
+    - [Nested `for` loops can both name `i` (fixed)](#nested-for-loops-can-both-name-i-fixed)
+    - [Snapshot tests are brittle](#snapshot-tests-are-brittle)
+    - [No browser e2e tests](#no-browser-e2e-tests)
+  - [7. When NOT to use Rip App](#7-when-not-to-use-rip-app)
 
 ---
 
@@ -185,7 +201,7 @@ A deep reactive proxy with path navigation. Single-app state,
 JSON-persistable, fine-grained signal subscription per key.
 
 ```rip
-app = stash
+app = createStash
   user:
     name: "Alice"
     prefs:
@@ -205,7 +221,7 @@ app.keys 'user'                  # → ['name', 'prefs']
 app.join 'user', email: "..."    # shallow merge
 
 # Use raw object underneath
-plain = raw(app)                 # back to a plain JS object
+plain = unwrapStash(app)         # back to a plain JS object
 ```
 
 **Single-stash policy**: Rip App assumes one stash per page (the one
@@ -291,6 +307,7 @@ router = createRouter components,
 
 router.push '/users/42?tab=settings'
 router.replace '/login'
+router.push '/cart', noScroll: true   # don't reset scroll on this nav
 router.back()
 router.forward()
 
@@ -316,6 +333,65 @@ The renderer uses `router.current` to drive its mount effect. Each
 field is also a separate signal so subscribers can track only what
 they care about.
 
+#### Anchor opt-outs and active-link styling
+
+The router intercepts plain `<a>` clicks at the document level. Two
+per-anchor attributes adjust that behavior:
+
+| Attribute               | Effect                                                                                |
+| ----------------------- | ------------------------------------------------------------------------------------- |
+| `data-router-ignore`    | Skip SPA interception entirely. The browser performs a full navigation.               |
+| `data-router-noscroll`  | Take the SPA navigation, but don't reset scroll to `(0, 0)`.                          |
+
+Anchors with `target="_blank"`, `[download]`, cross-origin hrefs, or
+hrefs outside `base` are also skipped automatically.
+
+**Active-link highlighting.** On every navigation the router walks
+in-document anchors and sets `aria-current` on those that match the
+current path:
+
+- exact match → `aria-current="page"`
+- prefix match (`/blog` on `/blog/123`) → `aria-current="true"`
+- otherwise → attribute removed (only if the router set it)
+
+Style it with attribute selectors — no per-link boilerplate needed:
+
+```css
+nav a[aria-current="page"] { color: red; font-weight: bold; }
+nav a[aria-current="true"] { color: red; }
+```
+
+Setting `aria-current` manually on an anchor wins — the router only
+touches values it set itself.
+
+**Scroll restoration.** New navigations (`push` or a link click)
+reset scroll to `(0, 0)`. Back/forward (`popstate`) restores the
+scroll position the page had when you left it. Same-document fragment
+links (`#section`) defer to the browser.
+
+**Typed routes (compile-time).** In a typed project (one with
+`rip.strict: true` or `::` annotations), `rip check` synthesizes a
+`__RipRoutes` union from the file tree under `app/routes/` and
+threads it through three places:
+
+| Place                              | Type                                                                  | Catches                            |
+| ---------------------------------- | --------------------------------------------------------------------- | ---------------------------------- |
+| `<a href: "...">` in render blocks | `__RipRoutes` for `/`-prefixed literals; any string otherwise         | Typos in known routes              |
+| `router.push url, opts?`           | `__RipRoutes` (replaces base `string`)                                | Typos in programmatic navigation   |
+| `@params` in `routes/[id].rip`     | `{ id: string }` (replaces `Record<string, string>`)                  | Typos like `@params.bogus`         |
+
+Anchor `href` uses a `const`-generic conditional: a literal starting
+with `/` must satisfy `__RipRoutes`, while external schemes
+(`https://`, `mailto:`, `tel:`), fragments (`#anchor`), and dynamic
+`string` values fall through unchecked. Typos like `<a href: "/crat">`
+produce a single-line error naming the valid routes.
+`router.replace` is deliberately left at `string` — it's commonly
+used to mutate the current URL with query strings, where the built
+value can't satisfy a literal-route union. Catch-all routes
+(`[...rest].rip`) are excluded from `__RipRoutes` — they're runtime
+404 fallbacks, not navigation targets, so including them as
+`/${string}` would defeat typo-catching for every other route.
+
 ### createRenderer
 
 The render loop. Subscribes to `router.current`, mounts/unmounts
@@ -422,6 +498,8 @@ mount(target)                  ← only the renderer calls this directly
                                   Per-child push wrap: each child's _create runs with
                                   child as current, so the child's reactive bindings
                                   register on child._disposers, not parent's.
+       beforeMount()           ← user hook; signals/state ready, DOM not yet in tree
+                                  effects created here auto-register on this component
        _setup()                ← post-creation effects (rare; most go in _init)
        mounted()               ← user hook; DOM is in the tree now
      __popComponent
@@ -436,6 +514,20 @@ unmount({ removeDOM = true })  ← idempotent (_unmounted flag short-circuits se
      DOM removal (if requested)
 ```
 
+### User hooks
+
+The framework recognizes these hook names on any component. All are
+optional; the runtime calls each only if defined.
+
+| Hook            | When it fires                                              | Notes                                                                            |
+| --------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `beforeMount`   | After `_create`, before DOM is attached                    | Effects created here auto-register on the component                              |
+| `mounted`       | After DOM attached                                         | Runs once per visit                                                              |
+| `beforeUnmount` | Before children unmount and disposers fire                 | Signals/effects still live                                                       |
+| `unmounted`     | After disposers fire and DOM is removed                    | Final notification; runs once per visit                                          |
+| `onError`       | A throw escapes any component method (render, hook, event) | Receives `{ status?, message?, error?, path? }`; the renderer walks the layout chain to find the nearest defining component |
+
+
 ### Effect ownership
 
 Every `__effect(fn)` call automatically registers its disposer with

package/docs/RIP-LANG.md

@@ -1593,12 +1593,11 @@ App = component
 
 ```coffee
 App = component
-  beforeMount = -> p "about to mount"
-  mounted     = -> p "mounted"
-  updated     = -> p "updated"
+  beforeMount   = -> p "about to mount"
+  mounted       = -> p "mounted"
   beforeUnmount = -> p "about to unmount"
-  unmounted   = -> p "unmounted"
-  onError     = (err, comp) -> p "caught: #{err.message}"
+  unmounted     = -> p "unmounted"
+  onError       = (err) -> p "caught: #{err.message}"
 ```
 
 **Effects:**