@ape-egg/vibe 2.3.0 → 3.0.1

package/ROADMAP.md

@@ -1,397 +0,0 @@
-# Vibe Roadmap
-
-Feature proposals and improvements for Vibe's runtime-first reactive framework.
-
----
-
-## Proposed: Manual Hydration API
-
-**Status**: Superseded by `$.reconcile()` (shipped in 1.9.0). See `runtime/reconcile.js` and the changelog entry. The reconciliation API solves the wholesale-replacement use cases listed below by walking the new source HTML against the live tree with a two-pointer aligner, preserving DOM identity, focus, and selection. Vibe-managed regions (iterations, conditionals, components, `<slot>` pairs) stay opaque. The shapes proposed below (`vibe.hydrate(el)` / `vibe.evaluate(html, state)` / `vibe.setHTML(el, html)`) were not implemented; `$.reconcile(target, source)` covers the same scenarios with a different ergonomic.
-**Original status**: Proposal
-**Priority**: Medium
-**Category**: Core Runtime
-
-### Problem
-
-Vibe's MutationObserver automatically hydrates `@[bindings]` on initial page load and incremental DOM changes, but fails when developers perform wholesale DOM replacement via `innerHTML`:
-
-```js
-// This doesn't trigger Vibe's hydration:
-element.innerHTML = '<h1>Welcome, @[race]!</h1>';
-// Result: Literal text "@[race]" instead of evaluated "human"
-```
-
-This happens because:
-1. `innerHTML` replacement destroys all old DOM nodes and creates new ones
-2. Vibe's MutationObserver is designed for incremental mutations, not complete replacement
-3. No mechanism exists to manually trigger re-hydration
-
-### Current Workaround
-
-Users must manually evaluate bindings before setting innerHTML:
-
-```js
-const evaluateBindings = (html) => {
-  return html.replace(/@\[([^\]]+)\]/g, (match, expression) => {
-    const keys = Object.keys(window.$);
-    const values = Object.values(window.$);
-    const result = new Function(...keys, `return ${expression}`)(...values);
-    return result ?? '';
-  });
-};
-
-element.innerHTML = evaluateBindings(html); // Manually evaluated
-```
-
-**Issues with this approach:**
-- Not DRY - duplicates Vibe's internal evaluation logic
-- Fragile - user's regex might not match Vibe's parser exactly
-- Knowledge burden - users need to know when manual evaluation is needed
-- Inconsistent - some bindings auto-hydrate, others need manual work
-
-### Use Cases
-
-This affects multiple real-world scenarios:
-
-1. **Dynamic content replacement** (tutorials, articles, modals)
-2. **Client-side routing** (replacing page sections with new HTML)
-3. **Lazy-loaded sections** (loading HTML from server with bindings)
-4. **Template cloning** (using `<template>` elements with `@[bindings]`)
-5. **Server-sent HTML** (SSR-like patterns where server sends HTML with bindings)
-
-### Proposed Solution
-
-Add a manual hydration API that allows users to trigger Vibe's binding evaluation:
-
-#### Option 1: Element Hydration
-```js
-vibe.hydrate(element);
-```
-
-**Usage:**
-```js
-tutorial.innerHTML = '<h1>Welcome, @[race]!</h1>';
-vibe.hydrate(tutorial); // Scan tutorial and children for @[bindings]
-```
-
-**Pros:**
-- Most flexible - works with any element
-- Matches web component patterns (`connectedCallback()`)
-- Clear intent - "scan this element"
-
-**Cons:**
-- Requires import/reference to vibe library
-- Two-step process (set innerHTML, then hydrate)
-
-#### Option 2: HTML String Evaluation
-```js
-const evaluated = vibe.evaluate(html, state);
-```
-
-**Usage:**
-```js
-const html = '<h1>Welcome, @[race]!</h1>';
-const evaluated = vibe.evaluate(html, window.$);
-tutorial.innerHTML = evaluated;
-```
-
-**Pros:**
-- Pure function - easier to test
-- Works without DOM access
-- Can be used server-side or in workers
-
-**Cons:**
-- Users must manage state passing
-- Doesn't handle nested/dynamic state updates
-
-#### Option 3: Safe innerHTML Setter
-```js
-vibe.setHTML(element, html);
-```
-
-**Usage:**
-```js
-vibe.setHTML(tutorial, '<h1>Welcome, @[race]!</h1>');
-```
-
-**Pros:**
-- Single operation - set and hydrate in one call
-- Matches platform APIs (`element.setHTML()`)
-- Simplest API surface
-
-**Cons:**
-- Yet another setter abstraction
-- Might conflict with future platform APIs
-
-### Recommendation
-
-**Implement Option 1** (`vibe.hydrate(element)`):
-- Aligns with Vibe's runtime-first philosophy
-- Gives users explicit control over hydration timing
-- Most flexible for different scenarios
-- Clear and predictable behavior
-
-### Implementation Notes
-
-```js
-// Expose on the state proxy:
-window.$ = state({ race: 'human' });
-window.$.vibe.hydrate(element); // Scan element for @[bindings]
-
-// Or as a module export:
-import state, { hydrate } from '@ape-egg/vibe';
-hydrate(element);
-```
-
-Should support:
-- Single element: `hydrate(tutorial)`
-- Multiple elements: `hydrate([el1, el2])`
-- Selector: `hydrate('tutorial')` (convenience)
-
-### Related
-
-Compare to other frameworks:
-- **Alpine.js**: `Alpine.initTree(el)` - manual initialization
-- **Vue**: `app.mount(el)` - mount to element
-- **Svelte**: Compiler handles this at build time
-- **HTMX**: `htmx.process(el)` - process element for attributes
-
----
-
-## Known Issues
-
-### innerHTML Replacement Corrupts Conditional Branches in Iterations
-
-**Status**: Bug
-**Priority**: Low (edge case)
-**Category**: Core Runtime
-**Discovered**: 2026-01-25
-
-#### Problem
-
-When a parent element containing iterations with nested conditionals has its `innerHTML` replaced multiple times with identical HTML, the conditional's `else` branches become `null` after 2-3 replacements. This causes conditionals to fail rendering.
-
-**Root cause:**
-1. Iteration template's `branches` object is shared across all iteration instances (iterate.js:65: `branches, // Branch templates are reused`)
-2. When `innerHTML` replacement happens, something mutates the shared `branches.else` to `null`
-3. All instances reference the same corrupted branches object
-4. Subsequent renders have no `else` branch template to mount
-
-#### Reproduction
-
-Programmatic test case:
-
-```js
-// HTML structure
-const html = `
-  <item-list>
-    <!-- each items as item, i -->
-    <item-card>
-      <span>@[item]</span>
-      <!-- if i % 2 === 0 -->
-      <badge>Even</badge>
-      <!-- else -->
-      <badge secondary>Odd</badge>
-      <!-- /if -->
-    </item-card>
-    <!-- /each -->
-  </item-list>
-`;
-
-// State
-window.$ = state({ items: ['Apple', 'Banana', 'Cherry'] });
-
-// Trigger the bug
-const container = document.querySelector('[vibe]');
-
-// First replacement: works
-container.innerHTML = html;
-await new Promise(r => setTimeout(r, 100));
-
-// Second replacement: works
-container.innerHTML = html;
-await new Promise(r => setTimeout(r, 100));
-
-// Third replacement: branches.else becomes NULL
-container.innerHTML = html;
-await new Promise(r => setTimeout(r, 100));
-
-// Result: Even/Odd badges fail to render in the third iteration
-```
-
-#### Observations
-
-1. Cloning `branches` object during iteration (shallow copy) doesn't prevent the bug
-2. The mutation happens BEFORE cloning, meaning the original template is corrupted
-3. Setting a property trap on `branches.else` doesn't catch the mutation (already null when accessed)
-4. Only affects conditionals inside iterations - standalone conditionals work fine
-5. Only triggers with multiple innerHTML replacements - single replacement works
-
-#### Affected Patterns
-
-This bug only affects:
-- Replacing innerHTML multiple times with identical HTML containing iterations + conditionals
-- Demo infrastructure like tutorial.js that re-renders on state changes
-- Not representative of typical usage patterns
-
-Does NOT affect:
-- Normal reactivity (state changes)
-- Single innerHTML replacement
-- Iterations without conditionals
-- Conditionals outside iterations
-- Incremental DOM mutations (appendChild, insertBefore, etc.)
-
-#### Workaround
-
-Avoid multiple innerHTML replacements on parents containing iteration+conditional templates. Instead:
-1. Use incremental DOM APIs (appendChild, createElement)
-2. Replace innerHTML once at initialization only
-3. Use Vibe's normal reactivity for updates
-4. Don't wrap demo content in `<tutorial>` that re-renders via innerHTML
-
-#### Investigation Log
-
-Debugging attempts (2026-01-25):
-- ✓ Confirmed `branches.else` becomes `null` after 3rd innerHTML replacement
-- ✓ Added deep cloning of branches object - didn't help (already null before clone)
-- ✓ Added Object.defineProperty trap - didn't fire (already null)
-- ✓ Checked parsing logic - correctly finds else comments
-- ✗ Unable to identify where mutation occurs
-- ✗ Unable to reproduce with simpler test case (needs tutorial.js pattern)
-
-Likely related to:
-- MutationObserver's removedNodes callback cleaning up references
-- Template caching/reuse strategy in iterate.js
-- Interaction between parse → clone → hydrate → render cycle
-
-#### Resolution Path
-
-**Recommended workaround today**: use `$.reconcile(target, source)` (shipped 1.9.0) instead of multiple raw `innerHTML` replacements. Reconcile is the supported path for wholesale HTML swaps and preserves vibe-managed regions cleanly. The original `innerHTML`-based reproduction is an unsupported pattern.
-
-**If the bug needs a proper fix** (not yet scheduled): deep investigation into branch reference lifecycle, deep-clone the branches metadata instead of sharing references, or rebuild conditional metadata on each replacement.
-
-This is acceptable technical debt since:
-1. Edge case not representative of normal usage
-2. Core reactivity (the 99% case) works correctly
-3. `$.reconcile` covers the wholesale-replacement scenarios that motivated this report
-4. Can be addressed if/when a real-world need to use raw `innerHTML` replacement surfaces
-
----
-
-## Proposed: `settled` Lifecycle Event (app quiescence)
-
-**Status**: Proposal
-**Priority**: Medium
-**Category**: Core Runtime / Lifecycle
-**Discovered**: 2026-06-16 (battle-brawlers: boss-unlock toast on the arena page)
-
-### Problem
-
-There is no event for *"the app has finished its initial boot/render churn and is now idle — run post-boot side-effects here."* The existing hooks don't cover it:
-
-- **`ready`** (`PHASE_READY`, removes `[vibe-fouc]` + dispatches `vibe:ready`) fires after the **first** render — but that first render is the *dataless/initial* state. Async data (e.g. a socket-loaded game state) arrives *after* `ready` and triggers a second, often **multi-second** data-driven re-render. So `ready` is "first paint," not "settled."
-- **`afterUpdate`** fires on **every** flush — it's a per-change signal, not a one-shot "we've quiesced" signal, and it fires *during* the churn.
-
-Consequently, state set imperatively right after boot is unreliable. Concrete case: pushing a toast (`$.notifications.push(...)`) when game state loads — the toast is added before the heavy first data render paints, the main thread is blocked through its 4s auto-dismiss window, and it's removed unseen. "The heavy boot churn eats it."
-
-### What it would accomplish
-
-A one-time, post-quiescence hook so consumers can reliably run boot-time side-effects: toasts/announcements, focus management, scroll restoration, analytics "app interactive", third-party widget init — anything that must happen *after* the initial render storm rather than during it.
-
-```js
-$.on('settled', () => notify.success('…'));   // lands; paints; lives its full duration
-```
-
-### Proposed shape
-
-`settled` fires **once per page load**, after: (a) Vibe's reactive flush queue has drained, and (b) the browser reports a free frame. Implementation sketch: when a flush completes with no further flush queued, schedule `requestIdleCallback(cb, { timeout })` (with a `setTimeout` fallback for Safari < 17); if still no flush was queued when it fires, dispatch `settled`.
-
-**Honest caveat — it's a heuristic, not a guarantee.** Perpetual tickers make true quiescence undecidable (battle-brawlers runs a 1s `setInterval` clock that flushes forever). This is the same class of fuzziness as Playwright's `networkidle` ("no requests for 500ms" — which Playwright now discourages as flaky). `settled` should mean "drained + one idle frame," documented as best-effort. Vibe *can* reliably know its own flush queue is empty; only external async (sockets/timers) is fuzzy, and the idle check bounds that.
-
-### Current workaround
-
-Hand-roll the idle wait at the call site with `requestIdleCallback`. See `webdev/webdev-game-stack/pages/the-arena.html` (boss-unlock toast): defer the toast to `requestIdleCallback({ timeout })` so it lands after the arena's heavy first render. Works, but every consumer re-implements it and must know it's needed.
-
-### Related (accurate precedents)
-
-- **Angular** — `ApplicationRef.isStable` (Observable) / `NgZone.onStable`: emits when the app has no pending micro/macro tasks. This is the genuine *app-level quiescence* analog to `settled`.
-- **Vue** — `nextTick()`: resolves after the current reactive flush → DOM updated. *Flush-level* (one flush), not full idle.
-- **Svelte** — `tick()`: resolves after pending state is applied to the DOM. Also flush-level.
-- **React** — no first-class app-settled signal; composed from `useEffect` + `requestIdleCallback`, or inferred via concurrent features (`useTransition` `isPending`, Suspense).
-
-**Not this:** `onMount` (Svelte) / `onMounted` (Vue) / `useEffect(fn, [])` (React) are **component-level "this component finished mounting"** hooks. They are *not* an app-wide quiescence signal and are not what `settled` proposes — don't model `settled` on them.
-
----
-
-## Proposed: Surgical HMR in Compiled (Hyperspeed) Mode
-
-**Status**: Proposal
-**Priority**: High (developer experience)
-**Category**: Compiler + Core Runtime (orchestrated by vite-plugin-vibe)
-**Discovered**: 2026-06-19 (battle-brawlers `dev:compiled` loop — a one-line edit to a leaf component recompiles every page that inlines it)
-
-### Problem
-
-Runtime mode already has surgical component HMR: vite-plugin-vibe refetches the changed component's source, calls `$.renderComponent(...)` + `$.reconcile(...)`, and patches **only the live instances** of that component — no page-level work. State is preserved by reusing the component ids.
-
-Compiled (hyperspeed) mode cannot do this today. The compiler **inlines components into each page's HTML and per-page manifest**, which *dissolves component identity*: the page manifest tree keeps the boundary as an anonymous positional node (`…→ component_1 → game-layout_0 → component_0 → …`) but nothing records *which source file produced it*. So the only invalidation the compiler can compute on a file save is the inverse graph — **component → dependent pages** — and it recompiles all of them.
-
-Concrete cost: `AccountProgression.html` is included by `Sidebar` and `Overlay`, both of which live in `Layout`, which **every** page mounts. One leaf edit → all 27 pages + 27 manifests recompiled (~2.7s), versus runtime mode's ~instant single-boundary patch.
-
-### Key realization — this is *not* "teach the compiler the runtime engine"
-
-The instinct is that surgical HMR means giving the Rust compiler the engine's runtime awareness (component instantiation, props, slots, live DOM) just to know what to recompile. It does **not**. Two things are already in place:
-
-1. **The runtime already ships the surgical engine** — `runtime/reconcile.js`, `runtime/component.js`, `runtime/component-cache.js`. Compiled pages boot the *same* runtime, so the patching machinery is already in the browser in compiled mode.
-2. **The compiler already builds the static include-graph** ("Building dependency graph…") and already knows component identity *during* inlining — it simply discards it in the output.
-
-What's missing is purely **emission + addressing**, not awareness:
-
-- The compiler needs to **stamp each boundary with its `src`** and (Option A) **emit each component's compiled subtree as its own small unit** that pages *reference* rather than absorb.
-- The runtime needs a **public boundary-swap API** built on the existing `reconcile` + `component-cache`, taking a recompiled unit + the live boundary and re-rendering just that subtree (live props/state stay the runtime's job — the compiler never needs them).
-
-The compiler and the engine have *converged on the same structural model from opposite ends* (both understand `<component src>` and the component tree). Surgical HMR **connects** those two seams through the tooling layer; it does not merge them, and it does not give the compiler runtime DOM awareness. The compiler's job stays build-time-static (include graph + boundary metadata); the runtime's job stays runtime-dynamic (props, state, DOM).
-
-### Layering constraint (non-negotiable)
-
-`vite-plugin-vibe` is **sugar on top**. The dependency direction is one-way:
-
-```
-vite-plugin-vibe  ──imports──▶  Vibe (compiler output + runtime public APIs)
-Vibe              ──never───▶   vite-plugin-vibe
-```
-
-- **Capabilities live in Vibe**, transport-agnostic:
-  - Compiler: emit boundary `src` identity; recompile a single component to its unit (`--watch` already incremental).
-  - Runtime: a public `swap(boundary, unit)` / `patchComponent(...)` API (reusing `reconcile`, `component-cache`, and component-id reuse for state preservation). Knows nothing about websockets or HMR.
-- **Orchestration lives in the plugin**: watch the compiler's `--watch` output, carry the recompiled unit over the dev websocket, call the runtime's swap API. The plugin already sends a `vibe:component-update` event in runtime mode — the compiled path emits the *same* event with a compiled payload.
-
-Neither the compiler nor the runtime gains a dependency on the plugin. The plugin remains optional sugar that delivers true HMR to **both** runtime dev and compiled dev.
-
-### Two implementation paths
-
-**Option A — per-component compiled units (full).**
-Compiler tags `component_N` boundaries with `src` and modularizes manifests so each component's subtree is a separately-emittable, separately-loadable module; pages reference units instead of inlining them. Repurpose the dep graph from *component→pages* to *component→its unit*. An edit recompiles one small unit. Runtime swaps boundaries from the new unit. **Manifest modularization is the bulk of the work** (today a page manifest is one ~440KB blob).
-
-**Option B — hybrid, recommended first (small lift).**
-In dev only, the compiler **keeps the boundary markers + the call-site props/slot** in the compiled output instead of fully dissolving them. On a component edit, the plugin treats *just that boundary* like a **runtime** component — refetch source → `renderComponent` + `reconcile` that one subtree — and leaves the rest of the page compiled. This reuses vite-plugin-vibe's existing runtime-HMR path almost verbatim; the **only** compiler change is "don't throw away boundary + props/slot metadata in a dev compiled build." Gets ~90% of the benefit; the edited boundary is re-expanded by the runtime engine rather than from a compiled unit (fine for dev).
-
-### Trade-offs
-
-- **Dev/prod divergence.** Inlining *is* hyperspeed; a boundary-preserving dev build is structurally different from the inlined prod build, so compiled-specific bugs (cross-boundary manifest merging, minified inlined scripts) may not reproduce in surgical-dev. Every framework lives with this (dev HMR builds ≠ prod). Keep **both** modes — surgical dev for iteration, full-inline compile for fidelity passes — and pick per task.
-- **Only internal edits go surgical.** Changing a *call site* (props/slot a page passes) still recompiles that page — same as runtime HMR re-mounting on a prop change.
-
-### Related (precedents — all do exactly this shape)
-
-- **Svelte** (`svelte-hmr` / Vite plugin): each component compiles to a module with an HMR proxy; a changed component hot-swaps its instances, preserving state where it can.
-- **Vue SFC HMR**: compiler stamps `__hmrId`; runtime `rerender`/`reload` patches just that component's instances.
-- **React Fast Refresh**: components compile with register/signature metadata + module boundaries; the refresh runtime re-renders only affected components, preserving hook state.
-- **Vite HMR boundaries**: `import.meta.hot.accept` — module-scoped patching instead of full reload.
-
-All three compile components into **independently-addressable, hot-swappable units with HMR boundaries**, then patch via a runtime accept API. This proposal is the same pattern adapted to Vibe's manifest model, with the orchestration deliberately kept in the (one-way-dependent) plugin.
-
----
-
-## Future Proposals
-
-*This section reserved for additional feature proposals*

package/compiler/bin/vibe-compile.js

@@ -1,121 +0,0 @@
-#!/usr/bin/env node
-
-import { spawn } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
-import { existsSync } from 'node:fs';
-import { platform, arch } from 'node:os';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const nativeDir = join(__dirname, '..', 'native');
-const originalCwd = process.cwd();
-
-// Map Node.js platform/arch to binary names
-const getPlatformBinary = () => {
-  const os = platform();
-  const cpu = arch();
-
-  const platformMap = {
-    'darwin-arm64': 'vibe-compiler-darwin-arm64',
-    'darwin-x64': 'vibe-compiler-darwin-x64',
-    'linux-x64': 'vibe-compiler-linux-x64',
-    'linux-arm64': 'vibe-compiler-linux-arm64',
-    'win32-x64': 'vibe-compiler-win32-x64.exe',
-  };
-
-  const key = `${os}-${cpu}`;
-  const binary = platformMap[key];
-
-  if (!binary) {
-    console.error(`Unsupported platform: ${os}-${cpu}`);
-    console.error('Supported platforms: darwin-arm64, darwin-x64, linux-x64, linux-arm64, win32-x64');
-    process.exit(1);
-  }
-
-  return binary;
-};
-
-// The wrapper is what gets killed (Ctrl+C, a dev server's child.kill(), a
-// process manager) — without forwarding, the compiler child survives as an
-// orphan whose watch lock blocks every future `--watch` on the same output.
-const wireLifecycle = (child) => {
-  ['SIGINT', 'SIGTERM', 'SIGHUP'].forEach((signal) =>
-    process.on(signal, () => child.kill(signal)),
-  );
-  process.on('exit', () => child.kill());
-};
-
-const run = () => {
-  const binary = getPlatformBinary();
-  const binaryPath = join(nativeDir, binary);
-  let userArgs = process.argv.slice(2);
-
-  // Handle subcommand: vibe compile [args]
-  // If first arg is "compile" or "c", remove it (the binary doesn't need it)
-  if (userArgs[0] === 'compile' || userArgs[0] === 'c') {
-    userArgs = userArgs.slice(1);
-  } else if (userArgs[0] && !userArgs[0].startsWith('-')) {
-    // Unknown subcommand
-    console.error(`Unknown subcommand: ${userArgs[0]}`);
-    console.error('Available subcommands: compile (or c)');
-    console.error('Usage: vibe compile [options]');
-    process.exit(1);
-  }
-  // If no subcommand provided, default to compile behavior (pass args as-is)
-
-  // Check if native binary exists
-  if (!existsSync(binaryPath)) {
-    // Fall back to cargo run for development
-    console.info('[vibe-compile] Native binary not found, building with cargo...');
-
-    const srcDir = join(__dirname, '..', 'src');
-
-    if (!existsSync(join(srcDir, 'Cargo.toml'))) {
-      console.error('Neither native binary nor Rust source found.');
-      console.error(`Expected binary at: ${binaryPath}`);
-      console.error(`Or Cargo.toml at: ${srcDir}`);
-      process.exit(1);
-    }
-
-    // Pass --cwd to tell the Rust binary the original working directory
-    const cargoArgs = ['run', '--release', '--', '--cwd', originalCwd, ...userArgs];
-
-    const cargo = spawn('cargo', cargoArgs, {
-      cwd: srcDir,
-      stdio: 'inherit',
-    });
-    wireLifecycle(cargo);
-
-    cargo.on('error', (err) => {
-      if (err.code === 'ENOENT') {
-        console.error('Cargo not found. Please install Rust: https://rustup.rs');
-      } else {
-        console.error('Failed to run cargo:', err.message);
-      }
-      process.exit(1);
-    });
-
-    cargo.on('close', (code) => {
-      process.exit(code ?? 0);
-    });
-
-    return;
-  }
-
-  // Run the native binary (it runs in the user's cwd, so no --cwd needed)
-  const child = spawn(binaryPath, userArgs, {
-    stdio: 'inherit',
-  });
-  wireLifecycle(child);
-
-  child.on('error', (err) => {
-    console.error('Failed to run vibe-compiler:', err.message);
-    process.exit(1);
-  });
-
-  child.on('close', (code) => {
-    process.exit(code ?? 0);
-  });
-};
-
-run();