@hyperfixi/engine 7.3.0 → 7.5.0

package/CHANGELOG.md

@@ -7,6 +7,136 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [7.5.0] - 2026-10-22
+
+What a live test of 7.3.0 found users hitting. The Vite plugin loads in a CommonJS project and
+ships types. MCP `diff_behaviors` compares whole handlers, and `npx` installs the engine.
+Hand-written non-English hyperscript that ran wrong in silence now reads right or says so. A
+minor: `@lokascript/htmx-adapter`'s `hx-on` change restores what its README always documented
+(bodies are JavaScript by default), and a page that relied on the engine switching them adds
+`<meta name="htmx-i18n-hx-on" content="hyperscript">`.
+
+### Changed
+
+- **`@lokascript/htmx-adapter`: `hx-on` bodies stay JavaScript unless the page opts in to
+  hyperscript bodies.** The adapter used to switch every `hx-on` body on the page to hyperscript
+  whenever a hyperscript engine (`window._hyperscript`) was loaded, and the documented stack (the
+  engine, htmx 4 and this adapter) always has one. So a plain-JavaScript
+  `hx-on:click="document.getElementById('o').textContent = 'ran'"` failed with a hyperscript parse
+  error, although the README says bodies are JavaScript by default. The opt-in is now explicit:
+  `<meta name="htmx-i18n-hx-on" content="hyperscript">`, or `setBodyExecutor()` as before. A page
+  that wrote hyperscript `hx-on` bodies and relied on the engine alone adds the `<meta>` tag. With
+  the tag and no engine on the page, the adapter warns and the bodies stay JavaScript.
+
+### Fixed
+
+- **`@hyperfixi/vite-plugin` loads in a CommonJS project.** `npm init -y` writes
+  `"type": "commonjs"`, and there the plugin's `require` build failed with
+  `ERR_PACKAGE_PATH_NOT_EXPORTED`: it requires `@hyperfixi/engine`, whose `exports` had only an
+  `import` condition. The engine's `exports` now name its ES module as the `default` too, which
+  Node 20.19+ and 22.12+ (what Vite 8 needs) can `require`.
+- **`@hyperfixi/vite-plugin` ships types for the app side** (`@hyperfixi/vite-plugin/client`):
+  the virtual module and `window.hyperfixi` / `window._hyperscript`. A TypeScript 6 project
+  rejected `import 'hyperfixi'` (`TS2882`). The README has a TypeScript section, with JSX's
+  `data-script` and an augmentation for `_`.
+- **The Vite plugin's scanner reads a `<script type="text/hyperscript">` block that contains
+  `<`** (`if n < 10`, a `<div/>` query). It skipped the whole block, so its commands were not
+  bundled and the page failed to parse. It also reads the `script` and `data-script` attributes,
+  which the engine runs as it runs `_`, and a production build scans Vite's `root` rather than the
+  working directory (`vite build app` from a parent directory bundled the siblings' modules).
+- **MCP `diff_behaviors` no longer calls any two multi-command or `if` handlers identical.** It
+  compared the operations it could extract, and it extracted single commands only: a `then` chain
+  (a `compound` node), an `if`, a loop and every command it had no extractor for gave nothing, so
+  `remove .b then wait 2s` and `remove .c then wait 5s` were "No semantic change", and so were an
+  English handler and an unrelated Spanish one. It now compares every command of a chain, both
+  branches of an `if`, a loop's body, and any other command with all its written roles (a
+  `fetch`'s `with` options included), and `this` is no longer read as `me`. Faithful translations
+  still compare identical (checked on chains, branches, loops and `wait for` in ja, es and ar).
+- **`npx @hyperfixi/mcp-server` installs the engine.** `@hyperfixi/engine`, `@hyperfixi/core` and
+  `@hyperfixi/server-bridge` were optional peers, which `npx` leaves out, so the documented
+  install checked nothing on the engine: every error only the engine catches came back `ok`, and
+  only stderr said so. They are dependencies now, and a validation whose engine check could not
+  run says so in the result (`ENGINE_CHECK_SKIPPED`, `info`; `get_diagnostics`:
+  `engine-check-skipped`). release-smoke installs the server alone and checks for the three.
+- **Validation warns on `this`** (`THIS_IS_NOT_ME`): hyperscript has no `this`, so
+  `toggle .a on this` or `put this.value.length into #n` reads a variable nobody set and does
+  nothing. These validated clean (6 of 10 clean-validating snippets that did nothing, in the 7.3.0
+  live test). The inert-shape warnings also reach commands after a `then` and inside an `if`'s
+  branches; they read only a block's `body` before.
+- **The IR `validate_and_compile` returns has the commands of a chain, a branch or a loop**: a
+  `then` chain is `compound` with each command in `body`, an `if` has `body` and `else`. A chain
+  came back as `compound` with no commands, so it could not be checked against an intent.
+- **AGENTS.md** said `this`, `and` or a comma between commands, and `put … in` work; all four fail
+  on both engines. Its worked example showed output the server no longer gives, and it quoted a
+  fidelity figure ("~76%") from before the renderer reached 100% on the corpus. Rewritten from the
+  server's real output.
+- **Multilingual: a native time unit after the event is a duration.** ko `클릭할 때 1초 대기`,
+  tr `tıklamada 1 saniye bekle` and ja `クリックで 1 秒 待つ` came back `on click 1 wait s`: the
+  number became a click count (the handler ran on the first click only) and the wait waited for
+  nothing, with no error. A number and the language's word for a unit after it, glued or spaced,
+  are one duration now (`wait 1s`, `wait 150ms`).
+- **Multilingual: a bare URL with a number in it translates.** `fetch /api/items/42` and
+  `fetch /api/slow?ms=300` were refused in every language, both ways ("would lose 42"): the check
+  counted the URL's numbers alone, and the translation writes the URL quoted. A bare URL is one
+  value now, the same as quoted.
+- **Multilingual: es and pt `esperar a <event>` waits for the event.** es `esperar a continue`
+  came back `wait continue`, a timed wait on a variable, which waits for nothing. `esperar a`
+  (es, pt) and `esperar por` (pt) read as `wait for`, as `esperar evento` already did.
+- **Multilingual: a hover word is `mouseenter`.** Eighteen languages' hover word (es `sobrevolar`,
+  fr `survol`, ko `호버`, …) read as `on hover`, which is not a DOM event, so the handler never ran.
+  They read as `on mouseenter` now; what `on mouseenter` is written as does not change.
+- **Multilingual: a dropped word with content of its own is refused, not dropped.** es
+  `al hacer clic fuera quitar .open de mí` came back `on click remove .open from me` (the dropdown
+  closed on every click): a particle the language maps to a word with meaning (`fuera`, `out`) was
+  skipped like a role marker. Such a translation is refused now (`LossyTranslationError`).
+- **`@lokascript/hyperscript-adapter` warns when a handler listens for a word nothing fires.**
+  A word the language does not know as an event (es `al pulsar …`, de `beim Tippen …`) runs as a
+  custom event of that name, and the handler never ran, silently. The adapter now warns once per
+  language and word. A name written as code (`miEvento`, `draggable:start`) stays quiet. No event
+  words were added: loka-js and our dictionaries ship the noun (`clic`), not the verbs. MCP
+  `validate_and_compile` reports the same, as an `UNKNOWN_EVENT_WORD` warning on non-English
+  input (`get_code_fixes` has its fix).
+
+## [7.4.0] - 2026-10-21
+
+Content htmx or fixi swaps in runs its hyperscript, as it does on upstream `_hyperscript`: the
+engine has upstream's htmx integration in every bundle, and loading the engine twice no longer
+binds every handler twice. A minor: new behavior and a deprecated option, nothing removed.
+
+### Fixed
+
+- **`@hyperfixi/engine`: content htmx or fixi swaps in runs its hyperscript, and htmx content a
+  script puts in issues its requests.** Upstream `_hyperscript` has this integration in its core
+  runtime and the engine had none: a `_="on click …"` that htmx swapped in did nothing, and an
+  `hx-get` that a script `put` into the page was never wired. The engine now has upstream's
+  integration (0.9.93's `htmx-compat.js`), installed by `boot()` in every bundle, the Vite
+  plugin's included: `htmx:load` (htmx 2) and `htmx:after:process` (htmx 4) process the content,
+  an after-process hook hands what a script inserts to `htmx.process`, and on htmx 4 it
+  registers upstream's `hs-include` extension (`hs-include=":id"` sends element-scoped variables
+  with the request; `htmx.config.extensions = "hs-include"` enables it). Two additions upstream
+  lacks: fixi (`fx:swapped` processes the swapped content), and pages with their own hooks
+  between the two (`htmx.onLoad(el => _hyperscript.process(el))`,
+  `_hyperscript.addAfterProcessHook(el => htmx.process(el))`, the workarounds until now) no longer
+  recurse, where upstream recurses until the stack runs out. The workarounds can be removed. The
+  first vendoring of upstream's suite left out its htmx tests (`integration/htmx.js`,
+  `ext/hs-include.js`), which is how the gap shipped; the gate now runs them and passes all 19
+  (1422/1486). `hyperfixi-hs.js` grows 0.7 KB gzipped, to 34.9 KB.
+- **`@hyperfixi/engine`: loading the engine twice no longer binds every handler twice.** Element
+  state was private to each copy of the engine, so the second copy initialised every element
+  again and one click ran its handler twice. htmx 4's boosted swaps run body scripts again, so
+  boost, then back, did it on a page that loads the engine at the end of its body. The state is
+  now `elt._hyperscript`, where upstream keeps it and a second copy finds it (two more of
+  upstream's tests pass).
+- **Examples: sortable-list's Add Task added a blank task and threw.** Its script read the input
+  with `first #new-item-input`, which is null (`first` of one element), and now reads the element
+  itself. tell-command's code sample shows its `on click`.
+
+### Deprecated
+
+- **`@hyperfixi/vite-plugin`'s `htmx` option does nothing.** It added a listener for htmx 2's
+  event names, which htmx 4 does not fire; the engine's integration covers every bundle. The
+  option is still accepted, so existing configs build.
+
 ## [7.3.0] - 2026-10-21
 
 `@hyperfixi/mcp-server` lists its 14 core tools by default and keeps the other 70 in toolsets

package/README.md

@@ -11,7 +11,7 @@ core's `dist/hyperfixi.js` is this package's `hyperfixi-hs.js`. It is also publi
 
 ## Install
 
-The script-tag bundle, hyperscript and nothing else (34.1 KB gzipped). It installs as
+The script-tag bundle, hyperscript and nothing else (34.9 KB gzipped). It installs as
 `window._hyperscript` and `window.hyperfixi`, and reads the document when it is ready:
 
 ```html
@@ -57,6 +57,20 @@ A script is rewritten as it is read. The element keeps the text its author wrote
 error in the rewritten script carries that text (`error.written`). `@lokascript/hyperscript-adapter`
 uses the hook when the host has it.
 
+### htmx and fixi
+
+Load htmx (2 or 4) or fixi beside any bundle and nothing else is needed: once the engine has
+processed the document it processes content they swap in, and hands htmx the content a script
+puts in, so its `hx-*` attributes work. On htmx 4 it registers upstream's `hs-include`
+extension (`hs-include=":userId"` sends an element-scoped variable with the request; enable it
+with `htmx.config.extensions = "hs-include"`). This is upstream's integration
+(`src/htmx-compat.ts`), with two additions: fixi (on `fx:swapped`), and a hand-off to htmx that
+does not recurse when a page also hands htmx's content to the engine itself
+(`htmx.onLoad(el => _hyperscript.process(el))`), as it does on upstream. As on upstream, the
+engine looks for htmx once, when it has processed the document: load htmx with a script tag
+(plain or `defer`, not `async`) for the hand-off and `hs-include`; swapped-in content is processed
+whenever htmx loads.
+
 ## Layout
 
 | File                                                             | What it holds                                                                                                                                                |
@@ -153,7 +167,7 @@ commands) 18.4 KB, `full` 34.1 KB, `core` (no commands) 13.8 KB.
 
 ## The script-tag bundle: `hyperfixi-hs.js`
 
-`dist/hyperfixi-hs.js` (minified, 34.1 KB gzipped; `hyperfixi-hs.dev.js` is the readable build) is the first product on this engine:
+`dist/hyperfixi-hs.js` (minified, 34.9 KB gzipped; `hyperfixi-hs.dev.js` is the readable build) is the first product on this engine:
 hyperscript and nothing else, every module, no htmx attributes, English only. It installs
 `window._hyperscript`, as upstream does, and the same object as `window.hyperfixi`. The name
 paired with core's `hyperfixi-hx.js` (hyperscript plus htmx, retired in Phase C3). Since C-R4b
@@ -185,8 +199,12 @@ gallery for `packages/core/test-pages/`. One behavior of core's is not in this e
 engine want `increment #count's textContent`. The examples write the second, which every
 bundle runs to the same count (the bundle matrix's Counter row).
 
-The 66 known failures: upstream's internal-API surface (`internals.tokenizer`,
-`evalStatically`, source info, error collection: 47), sockets and workers (17, upstream
+Since 2026-10-21 the gate also runs upstream's htmx tests (`integration/htmx.js` and
+`ext/hs-include.js`, 19), which the first vendoring left out, so the whole suite is 1,486. The
+engine failed 10 of them until it had upstream's htmx integration; it passes all 19.
+
+The 64 known failures: upstream's internal-API surface (`internals.tokenizer`,
+`evalStatically`, source info, error collection: 45), sockets and workers (17, upstream
 extensions that are not built), and two collection-expression tests that need upstream's
 component extension. Upstream's one failure is a test that expects its worker extension to be
 absent.

package/dist/common.js

@@ -37,13 +37,22 @@
     enter(_elt) {
     }
   };
-  var store = /* @__PURE__ */ new WeakMap();
-  var peekData = (elt) => store.get(elt);
-  var dropData = (elt) => store.delete(elt);
+  var windowHolders = /* @__PURE__ */ new WeakMap();
+  function holder(elt) {
+    if (elt.window !== elt) return elt;
+    let h = windowHolders.get(elt);
+    if (!h) windowHolders.set(elt, h = {});
+    return h;
+  }
+  var peekData = (elt) => holder(elt)._hyperscript;
+  function dropData(elt) {
+    const h = holder(elt);
+    const had = h._hyperscript !== void 0;
+    delete h._hyperscript;
+    return had;
+  }
   function dataOf(elt) {
-    let d = store.get(elt);
-    if (!d) store.set(elt, d = {});
-    return d;
+    return holder(elt)._hyperscript ??= {};
   }
   var rx = {
     /** True while an effect is evaluating: reads are then recorded as its dependencies. */
@@ -2400,6 +2409,108 @@
     };
   }
 
+  // src/htmx-compat.ts
+  var installed = /* @__PURE__ */ new WeakSet();
+  function installHtmxCompat(hs) {
+    if (installed.has(hs)) return;
+    installed.add(hs);
+    let fromHtmx = false;
+    const asHtmx = (f) => {
+      const was = fromHtmx;
+      fromHtmx = true;
+      try {
+        f();
+      } finally {
+        fromHtmx = was;
+      }
+    };
+    document.addEventListener(
+      "htmx:load",
+      (evt) => asHtmx(() => hs.process(evt.detail?.elt))
+    );
+    document.addEventListener("htmx:after:process", (evt) => asHtmx(() => hs.process(evt.target)));
+    document.addEventListener("fx:swapped", (evt) => {
+      const target = evt.detail?.cfg?.target;
+      hs.process(
+        target instanceof Element && target.isConnected ? target.parentElement ?? target : document.body
+      );
+    });
+    const htmx = Reflect.get(globalThis, "htmx");
+    if (typeof htmx?.process !== "function") return;
+    hs.addAfterProcessHook((elt) => {
+      if (!fromHtmx) asHtmx(() => htmx.process(elt));
+    });
+    if (htmx.version?.startsWith("4")) {
+      htmx.registerExtension?.("hs-include", {
+        htmx_config_request(elt, detail) {
+          const ctx = detail?.ctx;
+          if (!ctx) return;
+          const found = findHsInclude(ctx.sourceElement || elt);
+          if (!found) return;
+          const vars = resolveSpecifiers(found.value, found.scopeElt);
+          const body = ctx.request?.body;
+          if (body instanceof FormData) for (const k in vars) body.set(k, vars[k]);
+        }
+      });
+    }
+  }
+  function findHsInclude(sourceElt) {
+    const attr = sourceElt.getAttribute("hs-include");
+    if (attr !== null) return { value: attr, scopeElt: sourceElt };
+    for (let elt = sourceElt.parentElement; elt; elt = elt.parentElement) {
+      const inherited2 = elt.getAttribute("hs-include:inherited");
+      if (inherited2 !== null) return { value: inherited2, scopeElt: elt };
+    }
+    return null;
+  }
+  var readScope = (elt) => elt && peekData(elt)?.scopes?.elementScope || {};
+  function serialize(value) {
+    if (value == null) return "";
+    if (typeof value === "object") {
+      try {
+        return JSON.stringify(value);
+      } catch {
+        return "";
+      }
+    }
+    return String(value);
+  }
+  function resolveInherited(scopeKey, startElt) {
+    for (let elt = startElt; elt; elt = elt.parentElement) {
+      const scope = readScope(elt);
+      if (scopeKey in scope) return scope[scopeKey];
+    }
+    return void 0;
+  }
+  function resolveSpecifiers(attrValue, scopeElt) {
+    const result = {};
+    const raw = attrValue.trim();
+    if (raw === "*") {
+      const scope = readScope(scopeElt);
+      for (const k of Object.keys(scope)) result[k[0] === ":" ? k.slice(1) : k] = serialize(scope[k]);
+      return result;
+    }
+    for (let part of raw.split(",")) {
+      part = part.trim();
+      if (!part) continue;
+      if (part[0] === ":") {
+        const scope = readScope(scopeElt);
+        if (part in scope) result[part.slice(1)] = serialize(scope[part]);
+      } else if (part[0] === "^") {
+        const value = resolveInherited(":" + part.slice(1), scopeElt);
+        if (value !== void 0) result[part.slice(1)] = serialize(value);
+      } else if (part[0] === "#") {
+        const colon = part.lastIndexOf(":");
+        if (colon > 0) {
+          const scope = readScope(document.querySelector(part.slice(0, colon)));
+          const name = part.slice(colon + 1);
+          if (":" + name in scope) result[name] = serialize(scope[":" + name]);
+        }
+      }
+    }
+    return result;
+  }
+
   // src/parser.ts
   var ParseError = class extends Error {
     constructor(message, token, source, expected) {
@@ -2681,14 +2792,21 @@
   }
   var beforeProcess = [];
   var afterProcess = [];
+  var processing = /* @__PURE__ */ new Set();
   function processNode(node) {
     if (!(node instanceof Element || node instanceof Document || node instanceof DocumentFragment))
       return;
-    for (const hook of beforeProcess) hook(node);
-    const selector = attributes().map((a) => `[${a}]`).join(", ") + ", [type='text/hyperscript']";
-    if (node instanceof Element && node.matches(selector)) initElement(node);
-    node.querySelectorAll(selector).forEach(initElement);
-    for (const hook of afterProcess) hook(node);
+    if (processing.has(node)) return;
+    processing.add(node);
+    try {
+      for (const hook of beforeProcess) hook(node);
+      const selector = attributes().map((a) => `[${a}]`).join(", ") + ", [type='text/hyperscript']";
+      if (node instanceof Element && node.matches(selector)) initElement(node);
+      node.querySelectorAll(selector).forEach(initElement);
+      for (const hook of afterProcess) hook(node);
+    } finally {
+      processing.delete(node);
+    }
   }
   function cleanup(elt) {
     const data = peekData(elt);
@@ -2734,7 +2852,7 @@
     cleanup,
     /** The part of upstream's `internals` that pages and tests reach for. */
     internals: { runtime: { cleanup, processNode } },
-    version: false ? "dev" : "7.3.0"
+    version: false ? "dev" : "7.5.0"
   });
   function boot() {
     Object.assign(globalThis, { _hyperscript: api });
@@ -2742,6 +2860,7 @@
     const start = () => {
       processNode(document.documentElement);
       document.dispatchEvent(new Event("hyperscript:ready"));
+      installHtmxCompat(api);
     };
     if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", start);
     else setTimeout(start);