@ape-egg/vibe 3.0.5 → 4.0.0

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.0** — 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.0",
   "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

@@ -506,8 +506,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`);

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.0';
 
 // 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/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;