@ape-egg/vibe 3.0.5 → 4.0.1

package/README.md

@@ -1,6 +1,6 @@
 # Vibe
 
-**Version 3.0.5** — Runtime-first reactivity for plain HTML. Drop a script tag into any page and get reactive bindings, control flow, and URL-loaded components — no build step required. Compile later if you want; the compiler is a separate, optional package (`@ape-egg/vibe-compiler`).
+**Version 4.0.1** — Runtime-first reactivity for plain HTML. Drop a script tag into any page and get reactive bindings, control flow, and URL-loaded components — no build step required. Compile later if you want; the compiler is a separate, optional package (`@ape-egg/vibe-compiler`).
 
 ## Security model & CSP
 
@@ -196,7 +196,7 @@ How it works:
 
 1. `component({...})` generates a unique id (e.g. `_c0`, `_c1`) and registers the state at `$[id]`
 2. The `<script>` and every following sibling is tagged with `data-vibe-component-id="<id>"`
-3. Inside that subtree, `@[this.X.Y]` is rewritten to `@[_c0.X.Y]` and event handlers like `onclick="this.method()"` or `oninput="$.this.value = ..."` are rewritten to address `$[id]`
+3. Inside that subtree, `@[this.X.Y]` is rewritten to `@[_c0.X.Y]`, and `this.` in event handlers resolves at fire time by declared keys: names registered in `component({...})` address `$[id]` (`onclick="this.method()"`, `this.count++`), every other name reaches the native element (`this.value`, `this.closest(...)`, `this.focus()`). `$.this.X = ...` is always an explicit state write
 4. When the component leaves the DOM, its state entry is freed automatically
 
 Multi-segment paths (`@[this.user.profile.name]`), conditionals (`<!-- if this.editing -->`), and iterations (`<!-- each this.items as item -->`) all resolve against the component's bucket. Global `$` and component `this.X` coexist freely.

package/llms.txt

@@ -290,7 +290,7 @@ Use standard inline event handlers — they execute against `$` directly:
 <form onsubmit="event.preventDefault(); handleSubmit()">
 ```
 
-Inside a component, `this.X` references the component's bucket (rewritten at parse time); `this.value`, `this.checked`, `this.dataset` etc. still reach the DOM element since DOM properties are preserved.
+Inside a component, `this.X` resolves at fire time: keys declared in `component({...})` reference the component's bucket, every other name reaches the native DOM element (`this.value`, `this.dataset`, `this.nextElementSibling`, `this.closest(...)`, `this.focus()` — the whole DOM API). Declaring a key claims that name for state within the component's handlers; reach the shadowed element property through `event.currentTarget` if you need both.
 
 ## Dynamic Elements
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ape-egg/vibe",
-  "version": "3.0.5",
+  "version": "4.0.1",
   "type": "module",
   "description": "Runtime-first reactivity for plain HTML — no build step, no virtual DOM, no new syntax to learn",
   "main": "index.js",

package/runtime/component.js

@@ -484,6 +484,16 @@ export const forceRemount = (el, debug = false) => {
   processSingle(el, debug);
 };
 
+// A src still carrying an @[…] binding is not a URL — it's source material
+// (an iteration or branch template the renderer hasn't consumed yet, or an
+// outlet whose scope owner hasn't resolved it). Fetching it verbatim is never
+// right: initializeBlock substitutes loop-scoped srcs, hydration remounts
+// reactive outlets, and this pass only mounts real URLs.
+const hasUnresolvedSrc = (el) => {
+  BINDING_REGEX.lastIndex = 0;
+  return BINDING_REGEX.test(el.getAttribute('src'));
+};
+
 // Check if an element is nested inside another unprocessed component[src]
 const isNestedInUnprocessedComponent = (el, rootElement) => {
   let parent = el.parentElement;
@@ -506,8 +516,10 @@ const isNestedInUnprocessedComponent = (el, rootElement) => {
 // any trailing `.Y.Z` chain), so `@[this.user.name]` and `@[this.x + 1]` both
 // resolve correctly. Outside bindings — i.e. event handler attribute bodies
 // like `onclick="$.this.mode = 'edit'"` — only `$.this.X` writes are
-// rewritten; bare `this.X` reads in event handlers are handled later by
-// parse.js (which preserves DOM properties like `this.value`).
+// rewritten; bare `this.X` in event handlers is handled later by parse.js,
+// which lowers it to `$this(this).X` — resolved at fire time by
+// this-scope.js (declared state keys hit the bucket, everything else stays
+// the native element).
 const rewriteBindingsInString = (str, componentId) =>
   str.replace(BINDING_REGEX, (match, expr) => {
     const rewritten = expr.replace(THIS_PROP_REGEX, `${componentId}.$1`);
@@ -1048,11 +1060,12 @@ export const processComponent = (rootElement, onComplete, config = {}) => {
     return;
   }
 
-  // Only process top-level components — skip those nested inside other
+  // Only process top-level components with a fetchable src — skip unresolved
+  // binding srcs (never fetchable), and skip those nested inside other
   // unprocessed component[src] elements (they're slot content that will
   // be revealed when the parent component finalizes).
   const topLevel = Array.from(allComponents).filter(
-    (el) => !isNestedInUnprocessedComponent(el, rootElement)
+    (el) => !hasUnresolvedSrc(el) && !isNestedInUnprocessedComponent(el, rootElement)
   );
 
   if (topLevel.length === 0) {

package/runtime/constants.js

@@ -1,6 +1,6 @@
 // The released version — check-release.js holds this in lockstep with
 // package.json, the READMEs and the CHANGELOG.
-export const VERSION = '3.0.5';
+export const VERSION = '4.0.1';
 
 // Debug logger name
 export const DEBUGGER_NAME = '[vibe-debug]:';
@@ -176,45 +176,6 @@ export const VALUE_ATTRS = [
 // Properties that should be set directly on the DOM element (not as attributes)
 export const DOM_PROPERTIES = ['value', 'checked', 'selected'];
 
-// DOM element properties that should NOT be rewritten in event handlers
-// When parsing onclick="this.value = this.inputValue", preserve this.value (DOM) but rewrite this.inputValue (component state)
-export const DOM_ELEMENT_PROPERTIES = new Set([
-  'value',
-  'checked',
-  'selected',
-  'disabled',
-  'readOnly',
-  'files',
-  'tagName',
-  'nodeName',
-  'nodeType',
-  'classList',
-  'className',
-  'id',
-  'innerHTML',
-  'outerHTML',
-  'textContent',
-  'innerText',
-  'parentElement',
-  'parentNode',
-  'nextSibling',
-  'previousSibling',
-  'firstChild',
-  'lastChild',
-  'children',
-  'childNodes',
-  'offsetWidth',
-  'offsetHeight',
-  'clientWidth',
-  'clientHeight',
-  'scrollTop',
-  'scrollLeft',
-  'scrollWidth',
-  'scrollHeight',
-  'style',
-  'dataset',
-  'attributes',
-]);
 
 // Regex for matching reactive bindings (@[expression])
 // Supports nested brackets, single-quoted and double-quoted strings inside expressions:

package/runtime/iterate.js

@@ -493,6 +493,24 @@ const resolveSlotContentBindings = (el, scopedState, aliases) => {
   }
 };
 
+// Substitute the loop-scoped `@[expr]` parts of a component's src with their
+// values from this block's scope. Only exprs whose dependencies include a loop
+// alias are resolved — everything else keeps its binding form (see the caller
+// in initializeBlock for why). An expr that evaluates to undefined stays raw
+// too, so the unresolved-src invariant keeps the wrapper unfetchable instead
+// of composing a garbage URL.
+const resolveScopedSrc = (el, scopedState, scopeKeys) => {
+  const src = el.getAttribute('src');
+  BINDING_REGEX.lastIndex = 0;
+  if (!BINDING_REGEX.test(src)) return;
+  const resolved = src.replace(BINDING_REGEX, (match, expr) =>
+    extractDependencies(expr).some((dep) => scopeKeys.has(dep))
+      ? (evalInScope(expr, scopedState, el) ?? match)
+      : match,
+  );
+  if (resolved !== src) el.setAttribute('src', resolved);
+};
+
 // For <component src> elements inside an iteration instance, evaluate any
 // `@[expr]` attribute bindings against the iteration's scoped state and route
 // every resolved value through the global iteration-prop registry. The prop
@@ -1016,10 +1034,22 @@ export const initializeBlock = (templateNodes, scopedState, cachedTree = null, c
   // el.innerHTML (next microtask, when MutationObserver fires) the inactive branch templates
   // would be gone. cloneNode(true) does not copy expando JS properties, so we must (re)capture
   // _vibeSlotContent on every clone.
+  //
+  // Also resolve loop-scoped src bindings here, BEFORE parse() reads the
+  // attribute: the loop locals die with this render, so a src composed from
+  // them (`src="/x/@[item.slug].html"`) must become a literal URL now. Left as
+  // a binding it registers in this block's tree, and the remount transport
+  // (_vibeSrcBinding → data-vibe-src on the finalized wrapper) re-evaluates it
+  // against GLOBAL state on reparse — clobbering the mounted row with a fetch
+  // of a garbage URL. Exprs that read no loop alias stay raw: a reactive
+  // outlet (`src="@[page.src]"`) keeps its global binding, and an alias owned
+  // by a deeper loop resolves when that loop clones its own instances.
   const components = parseContainer.querySelectorAll('component[src], div.component[src]');
+  const scopeKeys = overlayKeysOf(scopedState);
   for (let i = 0; i < components.length; i++) {
     const el = components[i];
     if (el._vibeSlotContent === undefined) el._vibeSlotContent = el.innerHTML;
+    if (scopeKeys) resolveScopedSrc(el, scopedState, scopeKeys);
   }
 
   // Give this row its own component ids (compiled mode) before parse() reads the

package/runtime/parse.js

@@ -9,7 +9,6 @@ import {
   BINDING_REGEX,
   CONDITIONAL_REGEX,
   ITERATION_START_REGEX,
-  DOM_ELEMENT_PROPERTIES,
   DEHYDRATE_CLASS_OR_ATTR,
   THIS_PROP_REGEX,
   STATE_THIS_PROP_REGEX,
@@ -17,6 +16,7 @@ import {
   FETCH_SRC_ELEMENTS,
 } from './constants.js';
 import { rewriteHandlerAliases } from './loop-scope.js';
+import './this-scope.js';
 
 // Walks up the DOM for the nearest component wrapper tagged by component.js.
 // Used to rewrite `this.property` in event handlers to the component's state path.
@@ -125,7 +125,11 @@ const captureAttributeBindings = (element, aliasSet) => {
 
     // Event handlers get two compile-time rewrites, computed off the original
     // value and written once:
-    //   1. `this.property` → the component's state path (component-local state).
+    //   1. `this.` inside a component scope → `$this(this).` — resolved at
+    //      FIRE time by this-scope.js: declared state keys hit the bucket,
+    //      everything else stays the native element. Fire-time resolution is
+    //      load-bearing: compiled pages register component state after the
+    //      initial parse, so no key check is possible here.
     //   2. bare loop-variable aliases → `$scope(this,'alias')` (loop-scoped
     //      handlers — only when an enclosing <!-- each --> alias is in scope).
     if (attr.name.startsWith('on')) {
@@ -136,13 +140,11 @@ const captureAttributeBindings = (element, aliasSet) => {
           // `$.this.X` (component-state write through the root) must be
           // consumed as one reference BEFORE the bare `this.X` pass — that
           // pass alone would leave the `$.` prefix behind and produce
-          // `$.$['id'].X`. Runtime-fetched components arrive with this form
-          // already rewritten by component.js; compiled pages inline the
+          // `$.$this(this).X`. Runtime-fetched components arrive with this
+          // form already rewritten by component.js; compiled pages inline the
           // authored form, so parse meets it raw.
           v = v.replace(STATE_THIS_PROP_REGEX, (_, prop) => `$['${componentId}'].${prop}`);
-          v = v.replace(THIS_PROP_REGEX, (match, prop) =>
-            DOM_ELEMENT_PROPERTIES.has(prop) ? match : `$['${componentId}'].${prop}`,
-          );
+          v = v.replace(THIS_PROP_REGEX, (_, prop) => `$this(this).${prop}`);
         }
       }
       if (aliasSet && aliasSet.size > 0) {

package/runtime/this-scope.js

@@ -0,0 +1,53 @@
+// Event-handler `this.` resolution.
+//
+// parse.js rewrites `this.` in on* handlers inside a component scope to
+// `$this(this).` — this module is that `$this`. The returned proxy decides at
+// FIRE time, per access: a key declared in the component's state routes to
+// the state bucket; anything else routes to the native element (functions
+// bound so DOM methods keep their receiver, state methods left raw so `this`
+// inside them stays the proxy and nested writes stay reactive).
+//
+// The decision must happen at fire time, not parse time: compiled pages
+// register component state AFTER the initial parse (boot runs
+// executeCompiledComponentScripts post-parse, pre-hydrate), so a parse-time
+// key check would see empty buckets and mis-route every handler.
+//
+// Same delivery pattern as loop-scope's `$scope`: a global resolver keeps the
+// handler a readable native `on*` attribute.
+
+import { findComponentIdForElement } from './utils.js';
+
+const bucketFor = (element) => {
+  const componentId = findComponentIdForElement(element);
+  return componentId ? globalThis.$?.[componentId] : undefined;
+};
+
+export const resolveThisScope = (element) =>
+  new Proxy(element, {
+    get(el, prop) {
+      const bucket = bucketFor(el);
+      if (bucket && prop in bucket) return bucket[prop];
+      const value = el[prop];
+      return typeof value === 'function' ? value.bind(el) : value;
+    },
+    set(el, prop, value) {
+      const bucket = bucketFor(el);
+      if (bucket && prop in bucket) {
+        bucket[prop] = value;
+        return true;
+      }
+      if (bucket && globalThis.__vibe?.debug && !(prop in el)) {
+        console.warn(
+          `[vibe] handler assigned undeclared "this.${prop}" — it lands on the element, not component state. Declare it in component({...}) to make it reactive.`,
+        );
+      }
+      el[prop] = value;
+      return true;
+    },
+    has(el, prop) {
+      const bucket = bucketFor(el);
+      return (bucket && prop in bucket) || prop in el;
+    },
+  });
+
+globalThis.$this = resolveThisScope;