@ape-egg/vibe 3.0.4 → 4.0.0

package/README.md

@@ -1,6 +1,6 @@
 # Vibe
 
-**Version 3.0.4** — 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.4",
+  "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

@@ -11,7 +11,7 @@ import {
   ITERATION_START_REGEX,
 } from './constants.js';
 import { evalInScope } from './utils.js';
-import { bumpIterPropGeneration } from './iteration-utils.js';
+import { bumpIterPropGeneration, parkFetchableSrc } from './iteration-utils.js';
 import { fetchComponentTemplate, isComponentCached } from './component-cache.js';
 import { notifyChanged } from './state.js';
 import {
@@ -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`);
@@ -857,6 +859,10 @@ const processSingle = (el, debug) => {
           }
 
           newWrapper.innerHTML = transformedHtml;
+          // Park binding-valued src while the wrapper still lives in the inert
+          // document — adoption into the live document is what starts image
+          // loads, so this is the last moment a raw `@[...]` src is harmless.
+          parkFetchableSrc(newWrapper);
           if (firstComponentId !== null) {
             newWrapper.setAttribute('data-vibe-component-id', firstComponentId);
           }

package/runtime/constants.js

@@ -1,3 +1,7 @@
+// The released version — check-release.js holds this in lockstep with
+// package.json, the READMEs and the CHANGELOG.
+export const VERSION = '4.0.0';
+
 // Debug logger name
 export const DEBUGGER_NAME = '[vibe-debug]:';
 export const FOUC_CLASS_OR_ATTR = 'vibe-fouc'; // Class or attribute used to prevent FOUC (default: [vibe])
@@ -26,6 +30,16 @@ export const PHASE_HYPERSPEED = 'Hyperspeed'; // Restores @[...] markers from pr
 // Fetched components (<component src="">) are handled separately by processComponent()
 export const NON_REACTIVE_ELEMENTS = ['SCRIPT', 'HEAD', 'PRE'];
 
+// Elements whose src-family attributes the browser fetches the moment they are
+// set — a raw `src="@[binding]"` reaching one of these fires a network request
+// for the literal binding text before hydration can stamp the real value.
+// Bindings on them are parked on data-vibe-<attr> (the established transport)
+// until hydration writes the evaluated URL. <component src> is NOT here — its
+// src is consumed by processComponent, never by the browser.
+export const FETCH_SRC_ATTRS = ['src', 'srcset', 'poster'];
+export const FETCH_SRC_SELECTOR = 'img, source, iframe, video, audio, embed, track';
+export const FETCH_SRC_ELEMENTS = ['IMG', 'SOURCE', 'IFRAME', 'VIDEO', 'AUDIO', 'EMBED', 'TRACK'];
+
 // Attributes where the string value is meaningful (should NOT be removed when falsy)
 // All other attributes are treated as boolean-like (removed when falsy, present when truthy)
 export const VALUE_ATTRS = [
@@ -162,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/hydrate.js

@@ -1,7 +1,7 @@
 import { updateIteration } from './iterate.js';
 import { updateConditional, managedNodes } from './conditionals.js';
 import { liveComponentWrapper, remountComponent, forceRemount } from './component.js';
-import { isComponentWrapper, parkRootFor, parkBinding } from './staging.js';
+import { isComponentWrapper, isRemountTrigger, parkRootFor, parkBinding } from './staging.js';
 import { VALUE_ATTRS, DOM_PROPERTIES, BINDING_REGEX, PURE_BINDING_REGEX } from './constants.js';
 import {
   evalInScope,
@@ -177,11 +177,7 @@ export default (affected, state, manifest = {}, oldState = {}) => {
   const remountTriggers = [];
   const ordinary = [];
   for (const aff of affected) {
-    const isRemountTrigger =
-      aff.type === 'attribute' &&
-      (aff.attrName === 'src' || aff.attrName === 'key') &&
-      isComponentWrapper(aff.element);
-    (isRemountTrigger ? remountTriggers : ordinary).push(aff);
+    (isRemountTrigger(aff) ? remountTriggers : ordinary).push(aff);
   }
 
   const processEntry = (aff) => {

package/runtime/index.js

@@ -9,6 +9,7 @@ import { renderAllIterations, setRenderAllConditionals, releaseOrphanedIteration
 import { renderAllConditionals, branchNodeRegistry, managedNodes , settleConditionals} from './conditionals.js';
 import { installScopeResolver } from './loop-scope.js';
 import {
+  VERSION,
   NON_REACTIVE_ELEMENTS,
   PHASE_ATTACH,
   PHASE_PARSE,
@@ -40,6 +41,10 @@ import {
 // Wire up cross-module dependency after all modules are loaded
 setRenderAllConditionals(renderAllConditionals);
 
+// Stamped at module load, not boot — a console can read __vibe.version even
+// on a page whose boot died, which is exactly when a bug report needs it.
+((globalThis.__vibe ??= {}).version = VERSION);
+
 // Check if node should be processed by Vibe
 const shouldProcessNode = (node) => {
   // Only process element nodes
@@ -302,6 +307,18 @@ const mergeManifests = (hyperspeedTree, runtimeTree) => {
       mergedNode.runtime = runtimeNode.runtime;
     }
 
+    // The runtime parse of the live DOM is the ground truth for what exists.
+    // A manifest child with no runtime counterpart sits at an index the DOM
+    // no longer agrees with (a content script prepending into <body> shifts
+    // every sibling) — it can never bind an element, and hydrating its
+    // bindings would dereference null. Drop it; the runtime-discovered
+    // sibling added below carries the real element.
+    if (mergedNode.children) {
+      for (const key in mergedNode.children) {
+        if (!runtimeNode.children?.[key]) delete mergedNode.children[key];
+      }
+    }
+
     // Augment children recursively
     if (runtimeNode.children) {
       if (!mergedNode.children) mergedNode.children = {};

package/runtime/iteration-utils.js

@@ -1,5 +1,32 @@
 // Utility functions for array iteration
-import { ITERATION_REGEX, ITERATION_START_REGEX, CONDITIONAL_START_REGEX } from './constants.js';
+import {
+  ITERATION_REGEX,
+  ITERATION_START_REGEX,
+  CONDITIONAL_START_REGEX,
+  BINDING_REGEX,
+  FETCH_SRC_ATTRS,
+  FETCH_SRC_SELECTOR,
+} from './constants.js';
+
+// Move binding-valued src/srcset/poster on browser-fetchable elements to
+// data-vibe-<attr> so the literal `@[...]` text never becomes a fetchable URL.
+// Called on subtrees that are still in the inert document (component finalize)
+// — parse.js recaptures the parked binding under the real attribute name and
+// hydration writes the evaluated URL, which is the first value the browser
+// ever sees.
+export const parkFetchableSrc = (root) => {
+  const elements = root.querySelectorAll(FETCH_SRC_SELECTOR);
+  for (let i = 0; i < elements.length; i++) {
+    for (const attr of FETCH_SRC_ATTRS) {
+      const value = elements[i].getAttribute(attr);
+      BINDING_REGEX.lastIndex = 0;
+      if (value && BINDING_REGEX.test(value)) {
+        elements[i].setAttribute(`data-vibe-${attr}`, value);
+        elements[i].removeAttribute(attr);
+      }
+    }
+  }
+};
 
 // Parse an `each` directive body (the text inside `<!-- ... -->`, markers
 // stripped) into its parts, or null when it isn't a valid each. The index alias

package/runtime/parse.js

@@ -9,12 +9,14 @@ import {
   BINDING_REGEX,
   CONDITIONAL_REGEX,
   ITERATION_START_REGEX,
-  DOM_ELEMENT_PROPERTIES,
   DEHYDRATE_CLASS_OR_ATTR,
   THIS_PROP_REGEX,
   STATE_THIS_PROP_REGEX,
+  FETCH_SRC_ATTRS,
+  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.
@@ -75,6 +77,8 @@ const captureAttributeBindings = (element, aliasSet) => {
 
   const attributes = {};
   const nameBindings = [];
+  const isFetchableElement = FETCH_SRC_ELEMENTS.includes(nodeName);
+  let srcToPark = null;
 
   for (let j = 0; j < element.attributes.length; j++) {
     const attr = element.attributes[j];
@@ -88,6 +92,31 @@ const captureAttributeBindings = (element, aliasSet) => {
       continue;
     }
 
+    // A src-family binding parked on data-vibe-<attr> (by an earlier parse of
+    // this template, or by component finalize neutralizing fetched HTML):
+    // bind it to the real attribute — hydration writes the evaluated URL there.
+    if (isFetchableElement && attr.name.startsWith('data-vibe-')) {
+      const realName = attr.name.slice(10);
+      if (FETCH_SRC_ATTRS.includes(realName)) {
+        attributes[realName] = attr.value;
+        continue;
+      }
+    }
+
+    // A raw binding-valued src reaching a fetchable element fires a request
+    // for the literal `@[...]` text (innerHTML parse and cloneNode both
+    // trigger it). Park it on data-vibe-<attr> — after the loop, since
+    // removeAttribute would shift the live NamedNodeMap being iterated —
+    // so the template and every clone of it are inert until hydration.
+    if (isFetchableElement && FETCH_SRC_ATTRS.includes(attr.name)) {
+      BINDING_REGEX.lastIndex = 0;
+      if (BINDING_REGEX.test(attr.value)) {
+        attributes[attr.name] = attr.value;
+        (srcToPark ??= []).push([attr.name, attr.value]);
+        continue;
+      }
+    }
+
     // Attribute name itself contains a binding (e.g. <icon @[section.icon]>).
     if (BINDING_REGEX.test(attr.name)) {
       nameBindings.push(attr.name);
@@ -96,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')) {
@@ -107,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) {
@@ -128,6 +159,13 @@ const captureAttributeBindings = (element, aliasSet) => {
     }
   }
 
+  if (srcToPark) {
+    for (const [name, value] of srcToPark) {
+      element.setAttribute(`data-vibe-${name}`, value);
+      element.removeAttribute(name);
+    }
+  }
+
   return {
     attributes: Object.keys(attributes).length > 0 ? attributes : null,
     nameBindings: nameBindings.length > 0 ? nameBindings : null,

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;