@hyperfixi/testing-framework 3.2.0 → 3.3.0

package/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.3.0] - 2026-10-02
+
+The first publication of `@hyperfixi/engine`, the hyperscript engine meant to replace the one
+in `@hyperfixi/core`, and the example gallery moved onto it.
+
+### Added
+
+- **`@hyperfixi/engine` is published.** A hyperscript engine written against upstream
+  `_hyperscript`'s source, with upstream's own test suite as the acceptance oracle (1,401 of
+  1,467 tests; the 66 known failures are upstream's internal API, sockets and workers). It
+  ships `dist/hyperfixi-hs.js`, a script-tag bundle of hyperscript and nothing else, 34.1 KB
+  gzipped, which 36 of the repository's example pages now load instead of `hyperfixi.js`. It
+  keeps two forms upstream lacks, `new X(...)` and `toggle <element>`; the other hyperfixi-only
+  forms are not in it. It is typed (`tsc --strict`, no `any`), built from modules, and exposes
+  upstream's public API shape plus one hook, `addSourceTransform`, which
+  `@lokascript/hyperscript-adapter` uses to run the 24 languages on it.
+
+### Changed
+
+- **Examples and docs are written in upstream `_hyperscript`'s spelling** wherever upstream has
+  one: `put Y into X` for the `swap` strategies, `debounced at 300ms`, `matches`, `set X's @a`,
+  `increment #count's textContent` (core counted in a bare `#count`; upstream does not),
+  `on mutation of childList from #x`, `my offsetLeft` in place of `measure x`. The multilingual
+  reader still accepts the old forms; the renderer writes upstream's. Corpus rows follow.
+- **`@lokascript/semantic` renders `repeat for x in xs index i`** (was `with index`) and
+  `tell X show` (was `tell X to show`), upstream's spellings.
+- **The examples' bundle loader** takes a per-page default (`data-default="hs"`), and `?bundle=hs`
+  switches any page to the engine bundle.
+
+### Fixed
+
+- **`@hyperfixi/core`**: `toggle *display of X` parsed and then threw.
+- **Hybrid bundles (`hyperfixi-hx.js`)**: `increment` / `decrement` of a possessive wrote only
+  style properties; `increment #count's textContent` evaluated to the text and threw on
+  `querySelectorAll('0')`. They now write the property.
+- **`@lokascript/semantic`**: a template-literal URL in a Korean handler was read as a custom
+  event name.
+
 ## [3.2.0] - 2026-09-30
 
 A correctness release for multilingual hyperscript. The semantic parser behind
@@ -861,7 +899,9 @@ _Synchronized version release. See git history for details._
 - npm access token stored in GitHub Secrets
 - 2FA recommended for npm organization
 
-[Unreleased]: https://github.com/codetalcott/hyperfixi/compare/v3.1.0...HEAD
+[Unreleased]: https://github.com/codetalcott/hyperfixi/compare/v3.3.0...HEAD
+[3.3.0]: https://github.com/codetalcott/hyperfixi/compare/v3.2.0...v3.3.0
+[3.2.0]: https://github.com/codetalcott/hyperfixi/compare/v3.1.0...v3.2.0
 [3.1.0]: https://github.com/codetalcott/hyperfixi/compare/v3.0.0...v3.1.0
 [2.10.0]: https://github.com/codetalcott/hyperfixi/compare/v2.9.0...v2.10.0
 [2.9.0]: https://github.com/codetalcott/hyperfixi/compare/v2.8.0...v2.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperfixi/testing-framework",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Cross-platform behavior testing suite for LokaScript applications",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -29,7 +29,7 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
-    "pretest": "../../scripts/ensure-fresh.sh ../intent ../framework ../semantic ../hyperscript-adapter ../patterns-reference ../core ../aot-compiler ../compilation-service",
+    "pretest": "../../scripts/ensure-fresh.sh ../intent ../framework ../semantic ../hyperscript-adapter ../engine ../patterns-reference ../core ../aot-compiler ../compilation-service",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
@@ -41,7 +41,7 @@
     "typecheck": "tsc --noEmit",
     "test:check": "VITEST_TIMEOUT=240 VITEST_QUIET=1 bash ../../scripts/vitest-run.sh --reporter=dot",
     "test:canonical": "FOREIGN_CANONICAL_VALIDITY=1 VITEST_TIMEOUT=300 bash ../../scripts/vitest-run.sh --reporter=dot src/multilingual/canonical-validity.test.ts src/multilingual/foreign-canonical-validity.test.ts src/multilingual/render-fidelity.test.ts src/multilingual/bare-render-fidelity.test.ts src/multilingual/en-reference-preservation.test.ts",
-    "test:shipped-sources": "VITEST_TIMEOUT=300 bash ../../scripts/vitest-run.sh --reporter=dot src/multilingual/shipped-sources-validity.test.ts"
+    "test:shipped-sources": "VITEST_TIMEOUT=300 bash ../../scripts/vitest-run.sh --reporter=dot src/multilingual/shipped-sources-validity.test.ts src/multilingual/shipped-sources-engine.test.ts src/multilingual/shipped-examples-execution.test.ts"
   },
   "keywords": [
     "hyperscript",
@@ -57,11 +57,11 @@
   "author": "LokaScript Contributors",
   "license": "MIT",
   "dependencies": {
-    "@hyperfixi/core": "^3.2.0",
-    "@hyperfixi/patterns-reference": "^3.2.0",
-    "@lokascript/compilation-service": "^3.2.0",
-    "@lokascript/i18n": "^3.2.0",
-    "@lokascript/semantic": "^3.2.0",
+    "@hyperfixi/core": "^3.3.0",
+    "@hyperfixi/patterns-reference": "^3.3.0",
+    "@lokascript/compilation-service": "^3.3.0",
+    "@lokascript/i18n": "^3.3.0",
+    "@lokascript/semantic": "^3.3.0",
     "diff": "^8.0.3",
     "esbuild": "^0.25.12",
     "happy-dom": "^20.14.5",
@@ -73,7 +73,8 @@
     "vite": "^8.3.1"
   },
   "devDependencies": {
-    "@lokascript/hyperscript-adapter": "^3.2.0",
+    "@hyperfixi/engine": "^3.3.0",
+    "@lokascript/hyperscript-adapter": "^3.3.0",
     "@types/diff": "^5.0.0",
     "@types/node": "^26.6.3",
     "@vitest/coverage-v8": "^5.0.0",

package/src/multilingual/engine-parser-parity.test.ts

@@ -0,0 +1,67 @@
+/**
+ * Engine parser parity: the canonical-validity gates' strings on `@hyperfixi/engine`.
+ *
+ * Every English string those gates put to upstream `hyperscript.org`'s parser — each corpus
+ * row, its English re-render, and the English render of every authored translation — is put
+ * to the new engine's parser as well. The two must agree on whether it parses. The engine is
+ * meant to replace core's, and the multilingual product reaches an engine as English text, so
+ * a string upstream reads and the engine rejects (or the reverse) is a translation that works
+ * on one host and not the other.
+ *
+ * Unlike the foreign canonical-validity gate, this needs no fresh `populate`: it compares two
+ * parsers on the SAME strings, so a stale patterns.db changes which strings are asked, not
+ * whether the parsers agree. It always runs.
+ *
+ * On a failure, run one string on both engines:
+ * `npx tsx packages/engine/tools/probe.mts '<source>'`.
+ */
+import { describe, it, expect, beforeAll } from 'vitest';
+import {
+  checkCorpusRenderValidity,
+  loadCanonicalParser,
+  type CanonicalValidate,
+} from './canonical-validity';
+import { checkForeignRenderValidity } from './foreign-canonical-validity';
+
+describe('engine parser parity (R4 strings on @hyperfixi/engine)', () => {
+  const asked = new Set<string>();
+  const disagreements: string[] = [];
+
+  beforeAll(async () => {
+    const { api, everything, register } = await import('@hyperfixi/engine');
+    register(...everything);
+    const upstream = await loadCanonicalParser();
+    const engine: CanonicalValidate = source => {
+      try {
+        return api.parse(source).errors.map(error => error.message);
+      } catch (e) {
+        return ['threw: ' + (e instanceof Error ? e.message.split('\n')[0] : String(e))];
+      }
+    };
+    // Upstream's verdict is the one handed back, so the gates' own logic is unchanged.
+    const both: CanonicalValidate = source => {
+      const up = upstream(source);
+      if (!asked.has(source)) {
+        asked.add(source);
+        const mine = engine(source);
+        if ((up.length === 0) !== (mine.length === 0)) {
+          disagreements.push(
+            `${JSON.stringify(source)}\n      upstream: ${up[0]?.split('\n')[0] ?? 'accepts'}` +
+              `\n      engine:   ${mine[0]?.split('\n')[0] ?? 'accepts'}`
+          );
+        }
+      }
+      return up;
+    };
+    await checkCorpusRenderValidity({ validate: both });
+    await checkForeignRenderValidity({ validate: both });
+  }, 300_000);
+
+  it('asks about a real corpus (sanity: patterns.db has rows)', () => {
+    expect(asked.size).toBeGreaterThan(100);
+  });
+
+  it('the two parsers agree on every string', () => {
+    expect(disagreements).toEqual([]);
+  });
+});

package/src/multilingual/shipped-examples-execution.test.ts

@@ -17,6 +17,12 @@
  *   3. no allowlisted key has silently converged (stale entries must be
  *      removed so the list only ever ratchets down).
  *
+ * The same three run for the ENGINE LANE: `@hyperfixi/engine`, the engine meant
+ * to replace core's, against the same oracle on every handler upstream accepts
+ * (`allowedEngineDivergences` in the same baseline). It is the gate for a
+ * handler that parses on both engines and runs differently, which the
+ * parse-level list in shipped-sources-engine.test.ts cannot see.
+ *
  * To update after an intentional change: re-run and regenerate
  * `baselines/shipped-examples-execution.json` (the allowlist key embeds a
  * source hash, so FIXING a handler changes its key and assertion 3 forces the
@@ -54,6 +60,14 @@ interface AllowlistDoc {
     excerpt: string;
     reason: string;
   }>;
+  /** The engine lane: `@hyperfixi/engine` against upstream. */
+  allowedEngineDivergences: Array<{
+    key: string;
+    file: string;
+    event: string;
+    excerpt: string;
+    reason: string;
+  }>;
 }
 
 const baselinePath = path.resolve(
@@ -62,12 +76,17 @@ const baselinePath = path.resolve(
 );
 const allowlist = JSON.parse(readFileSync(baselinePath, 'utf8')) as AllowlistDoc;
 const allowed = new Set(allowlist.allowedDivergences.map(e => e.key));
+const allowedOnEngine = new Set(allowlist.allowedEngineDivergences.map(e => e.key));
+
+/** One sweep, shared by both lanes' tests. */
+let sweeping: Promise<ExecutionParityResult> | undefined;
+const sweep = (): Promise<ExecutionParityResult> => (sweeping ??= runShippedExamplesExecution());
 
 describe('shipped-examples execution gate', () => {
   let result: ExecutionParityResult;
 
   beforeAll(async () => {
-    result = await runShippedExamplesExecution();
+    result = await sweep();
 
     // Visibility, not assertions: what the sweep could not compare, and why.
     // A silently shrinking denominator is this gate's own blind spot.
@@ -84,6 +103,12 @@ describe('shipped-examples execution gate', () => {
     for (const [r, n] of [...reasons].sort((a, b) => b[1] - a[1])) {
       console.log(`[shipped-examples-execution]   skip ×${n}: ${r}`);
     }
+    const onEngine = result.engineCompared;
+    console.log(
+      `[shipped-examples-execution] engine lane: compared=${onEngine.length} ` +
+        `(vacuous=${onEngine.filter(c => c.vacuous).length}) ` +
+        `diverging=${onEngine.filter(c => !c.match).length}`
+    );
   }, 240_000);
 
   it('walks pages and compares handlers (sanity: extraction and both engines working)', () => {
@@ -142,6 +167,56 @@ describe('shipped-examples execution gate', () => {
   });
 });
 
+describe('shipped-examples execution gate: @hyperfixi/engine against upstream', () => {
+  let result: ExecutionParityResult;
+  beforeAll(async () => {
+    result = await sweep();
+  }, 240_000);
+
+  it('compares handlers on the engine (sanity: the lane ran and mostly agrees)', () => {
+    expect(result.engineCompared.length).toBeGreaterThan(90);
+    const realMatches = result.engineCompared.filter(c => c.match && !c.vacuous).length;
+    expect(realMatches).toBeGreaterThan(60);
+  });
+
+  it('has no NEW divergence from upstream outside the allowlist', () => {
+    const unexpected = result.engineCompared.filter(c => !c.match && !allowedOnEngine.has(c.key));
+    expect(
+      unexpected,
+      unexpected.length
+        ? `\nShipped handlers whose DOM effect on @hyperfixi/engine DIVERGES from the hyperscript.org ` +
+            `engine\n(the engine follows upstream's source: fix the engine, or allowlist with a reason ` +
+            `under allowedEngineDivergences):\n` +
+            unexpected
+              .map(
+                f =>
+                  `  [${f.key}]\n` +
+                  `      "${f.excerpt}"\n` +
+                  `      engine  : ${JSON.stringify(f.engineEffects).slice(0, 300)}\n` +
+                  `      upstream: ${JSON.stringify(f.upstreamEffects).slice(0, 300)}`
+              )
+              .join('\n') +
+            `\n\nOne source on both, on one page: npx tsx packages/engine/tools/probe.mts '<source>'`
+        : ''
+    ).toEqual([]);
+  });
+
+  it('has no stale allowlist entries', () => {
+    const stillDiverging = new Set(result.engineCompared.filter(c => !c.match).map(c => c.key));
+    const stale = allowlist.allowedEngineDivergences
+      .map(e => e.key)
+      .filter(k => !stillDiverging.has(k));
+    expect(
+      stale,
+      stale.length
+        ? `\nThese handlers no longer diverge on the engine (or were edited: the key embeds a\n` +
+            `source hash). Remove them from allowedEngineDivergences in\n` +
+            `baselines/shipped-examples-execution.json:\n  ${stale.join('\n  ')}`
+        : ''
+    ).toEqual([]);
+  });
+});
+
 describe('harness pieces', () => {
   it('extracts the trigger event from the leading on-clause', () => {
     expect(triggerEventOf('on click add .a to me')).toBe('click');

package/src/multilingual/shipped-examples-execution.ts

@@ -35,6 +35,15 @@
  * before/after snapshot around it. See runHandlerOnEngine for why isolation is
  * worth its cost.
  *
+ * ## The engine lane
+ * `@hyperfixi/engine` is meant to replace core's engine, so the same sweep
+ * runs it against the same oracle: every handler upstream accepts (whether or
+ * not core compiles it clean) is executed on upstream and on the engine, and
+ * the two effect signatures are compared (`engineCompared`). The parse-level
+ * list of what the engine rejects (shipped-sources-engine.test.ts) cannot see
+ * a handler that parses on both and runs differently; this can. A handler
+ * upstream accepts and the engine rejects is compared too, and diverges.
+ *
  * ## Node-only
  * Imports the real `hyperscript.org` build off disk and swaps jsdom globals
  * per handler execution (both engines resolve `document` lazily through
@@ -144,6 +153,18 @@ export interface ComparedHandler extends ShippedHandler {
   excerpt: string;
 }
 
+/** One handler run on upstream and on `@hyperfixi/engine`. */
+export interface EngineComparedHandler extends ShippedHandler {
+  key: string;
+  event: string;
+  engineEffects: string[];
+  upstreamEffects: string[];
+  match: boolean;
+  /** Both signatures empty: not evidence of parity (see ComparedHandler.vacuous). */
+  vacuous: boolean;
+  excerpt: string;
+}
+
 export interface ExecutionParityResult {
   /** Pages walked. */
   pages: number;
@@ -153,6 +174,8 @@ export interface ExecutionParityResult {
   compared: ComparedHandler[];
   /** Handlers excluded, each with its reason. */
   skipped: SkippedHandler[];
+  /** Handlers upstream accepts, executed on upstream and on `@hyperfixi/engine`. */
+  engineCompared: EngineComparedHandler[];
 }
 
 /** Stable key for one handler execution. */
@@ -219,6 +242,10 @@ export interface Engines {
   hyperfixiInstall(source: string, el: Element): Promise<void>;
   /** Install a handler on an element via the upstream engine. */
   upstreamInstall(el: Element): void;
+  /** `@hyperfixi/engine`'s parse errors for a source; [] = it parses. */
+  engineErrors(source: string): string[];
+  /** Install a handler on an element via `@hyperfixi/engine`. */
+  engineInstall(el: Element): void;
 }
 
 /**
@@ -311,7 +338,20 @@ export async function initEngines(): Promise<Engines> {
     processNode(el: Node): void;
   };
 
+  const engine = await import('@hyperfixi/engine');
+  engine.register(...engine.everything);
+
   return {
+    engineErrors(source) {
+      try {
+        return engine.api.parse(source).errors.map(e => e.message.split('\n')[0] ?? '');
+      } catch (e) {
+        return ['threw: ' + (e as Error).message.split('\n')[0]];
+      }
+    },
+    engineInstall(el) {
+      engine.api.processNode(el);
+    },
     compileClean(source) {
       try {
         const r = core.hyperscript.compileSync(source);
@@ -425,6 +465,7 @@ export async function runShippedExamplesExecution(opts?: {
 
   const compared: ComparedHandler[] = [];
   const skipped: SkippedHandler[] = [];
+  const engineCompared: EngineComparedHandler[] = [];
   let pages = 0;
   let handlers = 0;
 
@@ -438,6 +479,9 @@ export async function runShippedExamplesExecution(opts?: {
       handlers += pageHandlers.length;
 
       const eligible: Array<ShippedHandler & { event: string }> = [];
+      // The engine lane's denominator: dispatchable, deterministic, and upstream
+      // accepts it. Core's verdict is not part of it.
+      const oracle: Array<ShippedHandler & { event: string }> = [];
       for (const h of pageHandlers) {
         if (!h.event) {
           skipped.push({ ...h, reason: 'not an `on <event>` handler' });
@@ -452,6 +496,8 @@ export async function runShippedExamplesExecution(opts?: {
           skipped.push({ ...h, reason: disq.reason });
           continue;
         }
+        const upstreamErrs = engines.upstreamErrors(h.source);
+        if (upstreamErrs.length === 0) oracle.push(h as ShippedHandler & { event: string });
         if (!engines.compileClean(h.source)) {
           skipped.push({
             ...h,
@@ -459,14 +505,18 @@ export async function runShippedExamplesExecution(opts?: {
           });
           continue;
         }
-        const upstreamErrs = engines.upstreamErrors(h.source);
         if (upstreamErrs.length > 0) {
           skipped.push({ ...h, reason: `upstream rejects it (no oracle): ${upstreamErrs[0]}` });
           continue;
         }
         eligible.push(h as ShippedHandler & { event: string });
       }
-      if (eligible.length === 0) continue;
+      if (eligible.length === 0 && oracle.length === 0) continue;
+      // Upstream's signatures from the core lane serve the engine lane too when
+      // the two lanes install the same handlers on the page.
+      const sameHandlers =
+        eligible.length === oracle.length && eligible.every((h, i) => h === oracle[i]);
+      const upstreamRun = new Map<ShippedHandler, string[]>();
 
       // Both engines log runtime errors to the console during dispatch
       // (COMMAND FAILED etc.). That is expected data here — the effect
@@ -488,6 +538,7 @@ export async function runShippedExamplesExecution(opts?: {
           const theirs = await runHandlerOnEngine(html, eligible, h, (_hh, el) =>
             engines.upstreamInstall(el)
           );
+          upstreamRun.set(h, theirs);
           compared.push({
             ...h,
             key: keyFor(h),
@@ -498,6 +549,25 @@ export async function runShippedExamplesExecution(opts?: {
             excerpt: h.source.replace(/\s+/g, ' ').trim().slice(0, 100),
           });
         }
+        for (const h of oracle) {
+          const rejected = engines.engineErrors(h.source)[0];
+          const theirs =
+            (sameHandlers && upstreamRun.get(h)) ||
+            (await runHandlerOnEngine(html, oracle, h, (_hh, el) => engines.upstreamInstall(el)));
+          const ours =
+            rejected !== undefined
+              ? [`<engine rejects the source: ${rejected}>`]
+              : await runHandlerOnEngine(html, oracle, h, (_hh, el) => engines.engineInstall(el));
+          engineCompared.push({
+            ...h,
+            key: keyFor(h),
+            engineEffects: ours,
+            upstreamEffects: theirs,
+            match: JSON.stringify(ours) === JSON.stringify(theirs),
+            vacuous: ours.length === 0 && theirs.length === 0,
+            excerpt: h.source.replace(/\s+/g, ' ').trim().slice(0, 100),
+          });
+        }
       } finally {
         console.log = saved.log;
         console.warn = saved.warn;
@@ -507,5 +577,5 @@ export async function runShippedExamplesExecution(opts?: {
     }
   }
 
-  return { pages, handlers, compared, skipped };
+  return { pages, handlers, compared, skipped, engineCompared };
 }

package/src/multilingual/shipped-sources-engine.test.ts

@@ -0,0 +1,106 @@
+/**
+ * Shipped sources on `@hyperfixi/engine`: what replacing core's engine would break.
+ *
+ * `packages/engine` is meant to replace the engine in `packages/core`. Every
+ * hyperscript source this repository ships (`examples/` and the doc trees, the
+ * validity gate's collection) that core compiles clean is put to the engine's
+ * parser. The ones it rejects are listed in
+ * `baselines/shipped-sources-engine.json`, each with the reason it is still
+ * there. Three assertions, as the sibling gates:
+ *   1. sanity: sources were found and the engine reads most of them;
+ *   2. no NEW rejected source outside the list. A page or a doc example
+ *      written in syntax only core has would break when core's engine goes;
+ *      write upstream's spelling (`packages/engine/README.md` lists the forms
+ *      that were considered and not kept), or list it with a reason;
+ *   3. no stale entry: a listed source the engine now reads, or one that was
+ *      edited (the key embeds a hash of the source), must be removed, so the
+ *      list only shrinks. It is empty when core's engine can be replaced
+ *      without breaking a shipped page.
+ *
+ * This is a PARSE-level gate. A source can parse on both engines and run
+ * differently; the engine lane of `shipped-examples-execution.test.ts` is the
+ * gate for that.
+ *
+ * To see the list by form, and beside upstream's verdict:
+ * `npx tsx packages/engine/tools/shipped-sources.mts`.
+ */
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { JSDOM } from 'jsdom';
+import { describe, it, expect, beforeAll } from 'vitest';
+import {
+  checkShippedSourcesOnEngine,
+  type CompileForValidity,
+  type ShippedSourcesOnEngineResult,
+} from './shipped-sources-validity';
+
+interface RejectedDoc {
+  rejected: Array<{ key: string; file: string; error: string; excerpt: string; reason: string }>;
+}
+
+const baselinePath = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../baselines/shipped-sources-engine.json'
+);
+const listed = JSON.parse(readFileSync(baselinePath, 'utf8')) as RejectedDoc;
+const allowed = new Set(listed.rejected.map(e => e.key));
+
+describe('shipped sources on @hyperfixi/engine', () => {
+  let result: ShippedSourcesOnEngineResult;
+
+  beforeAll(async () => {
+    const core = (await import('@hyperfixi/core')) as unknown as {
+      hyperscript: { compileSync: CompileForValidity };
+    };
+    const { api, everything, register } = await import('@hyperfixi/engine');
+    register(...everything);
+    const dom = new JSDOM('<!doctype html><html><body></body></html>');
+    result = checkShippedSourcesOnEngine(
+      code => core.hyperscript.compileSync(code),
+      code => {
+        try {
+          return api.parse(code).errors.map(error => error.message);
+        } catch (e) {
+          return ['threw: ' + (e instanceof Error ? e.message : String(e))];
+        }
+      },
+      dom.window.document as unknown as Parameters<typeof checkShippedSourcesOnEngine>[2]
+    );
+  }, 120_000);
+
+  it('finds the shipped sources and the engine reads most of them (sanity)', () => {
+    expect(result.coreClean).toBeGreaterThan(200);
+    expect(result.engineAccepts).toBeGreaterThan(200);
+  });
+
+  it('has no NEW shipped source the engine rejects outside the list', () => {
+    const unexpected = result.rejections.filter(r => !allowed.has(r.key));
+    expect(
+      unexpected,
+      unexpected.length
+        ? `\nShipped sources core compiles and @hyperfixi/engine rejects (write upstream's spelling,\n` +
+            `or list it in baselines/shipped-sources-engine.json with a reason):\n` +
+            unexpected
+              .map(r => `  [${r.key}]\n      "${r.excerpt}"\n      -> ${r.error}`)
+              .join('\n') +
+            `\n\nOne source on the engine and on upstream, side by side:\n` +
+            `  npx tsx packages/engine/tools/probe.mts '<source>'`
+        : ''
+    ).toEqual([]);
+  });
+
+  it('has no stale entries (a source the engine now reads must be removed, so the list only shrinks)', () => {
+    const stillRejected = new Set(result.rejections.map(r => r.key));
+    const stale = listed.rejected.map(e => e.key).filter(key => !stillRejected.has(key));
+    expect(
+      stale,
+      stale.length
+        ? `\nThese listed sources are no longer rejected (read by the engine now, or edited: the key\n` +
+            `embeds a hash of the source). Remove them from baselines/shipped-sources-engine.json:\n  ` +
+            stale.join('\n  ')
+        : ''
+    ).toEqual([]);
+  });
+});

package/src/multilingual/shipped-sources-validity.ts

@@ -231,3 +231,68 @@ export function checkShippedSourcesValidity(
 
   return { checked: sources.length, clean, findings };
 }
+
+/** A shipped source `packages/core` compiles clean and `@hyperfixi/engine` rejects. */
+export interface EngineRejection extends ShippedSource {
+  /** Stable key: file plus a hash of the source, as the validity gate's. */
+  key: string;
+  /** The engine's first parse error, first line. */
+  error: string;
+  excerpt: string;
+}
+
+export interface ShippedSourcesOnEngineResult {
+  /** Distinct (file, source) pairs core compiles clean. */
+  coreClean: number;
+  /** Of those, the ones the engine parses. */
+  engineAccepts: number;
+  rejections: EngineRejection[];
+}
+
+/**
+ * What replacing core's engine with `@hyperfixi/engine` would break in the
+ * material we ship: every source core compiles clean, put to the engine's
+ * parser. `engineErrors` returns the engine's parse errors ([] = it parses).
+ *
+ * The denominator is core-clean sources on purpose. A source core itself
+ * rejects or recovers from is already broken where it is shipped, and is the
+ * validity gate's business; the question here is only what would STOP working.
+ */
+export function checkShippedSourcesOnEngine(
+  compile: CompileForValidity,
+  engineErrors: (code: string) => string[],
+  doc: Parameters<typeof extractHyperscriptFromMarkup>[0],
+  opts?: { roots?: string[]; repoRoot?: string }
+): ShippedSourcesOnEngineResult {
+  const seen = new Set<string>();
+  const rejections: EngineRejection[] = [];
+  let coreClean = 0;
+  let engineAccepts = 0;
+
+  for (const s of collectShippedSources(doc, opts)) {
+    const key = keyFor(s.file, s.source);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    let clean = false;
+    try {
+      const result = compile(s.source);
+      clean = result.ok && (result.errors ?? []).length === 0;
+    } catch {
+      /* not core-clean */
+    }
+    if (!clean) continue;
+    coreClean++;
+    const errors = engineErrors(s.source);
+    if (errors.length === 0) {
+      engineAccepts++;
+      continue;
+    }
+    rejections.push({
+      ...s,
+      key,
+      error: (errors[0] ?? '').split('\n')[0] ?? '',
+      excerpt: s.source.replace(/\s+/g, ' ').trim().slice(0, 100),
+    });
+  }
+  return { coreClean, engineAccepts, rejections };
+}

package/src/multilingual/validators/execution-validator.ts

@@ -72,9 +72,11 @@ export const EXECUTION_SUBSET: readonly string[] = [
   // patterns whose en reference now parses (the if/else conditional fold) and
   // executes (propertyAccess evaluator; matches/exists/is-empty condition
   // forms). Probed through this validator: each produces a non-empty,
-  // deterministic effect signature. `unless-condition` stays out — `unless` is
-  // deliberately NOT folded (see semantic-parser.tryParseConditionalBlock), so
-  // its flat parse still errors at runtime.
+  // deterministic effect signature. `unless-condition` stayed out while it was
+  // core's prefix `unless` (deliberately NOT folded: see
+  // semantic-parser.tryParseConditionalBlock; its flat parse errored at
+  // runtime). The row is `if I do not match …` since 2026-10-01 and has not
+  // been probed for this subset.
   'if-condition',
   'if-matches',
   'if-exists',

package/src/multilingual/value-matrix.accepted.test.ts

@@ -23,6 +23,9 @@ describe('value matrix: accepted pairs', () => {
       known!.reason
     );
     expect(acceptedReason('increment|#a.textContent', ['it', 'it/up'])).toBe(ambiguity!.reason);
+    expect(acceptedReason('increment|#a.textContent', ['it', 'it/up', 'it/eng'])).toBe(
+      ambiguity!.reason
+    );
   });
 
   it('leaves it open when one failing lane is not', () => {

package/src/multilingual/value-matrix.ts

@@ -49,7 +49,12 @@
  *              `render(parse_en(src), L)`, compiled with `{ language: L }`;
  *   - `<L>/up` the same translation through `@lokascript/hyperscript-adapter`
  *              (`preprocess`, back to English) on upstream: the multilingual
- *              product for original _hyperscript users.
+ *              product for original _hyperscript users;
+ *   - `eng`    the English source on `@hyperfixi/engine`, the engine that
+ *              replaces core's;
+ *   - `<L>/eng` the adapter's English (the string the `/up` lane runs) on
+ *              that engine: where it differs from `<L>/up`, the two ENGINES
+ *              differ, since they were given the same text.
  *
  * A (cell, lane) pair FAILS when its result differs from the oracle's.
  *
@@ -69,7 +74,9 @@
  *
  * A translation that loses a loop's condition can loop forever. Core caps a
  * loop at 10,000 iterations; upstream has no cap and blocks the thread, so
- * every upstream run gets an evaluation budget (see EVAL_BUDGET).
+ * every upstream run gets an evaluation budget (see EVAL_BUDGET). The new
+ * engine has no cap and no hook for one: a string that spent the budget on
+ * upstream is not run on it, and its `/eng` lane reads `✗budget` too.
  *
  * Node-only: imports the real `hyperscript.org` build off disk and needs the
  * node vitest environment (see the shipped-examples gate for why).
@@ -733,7 +740,8 @@ export const FOREIGN_LANGUAGES = [
 export const LANES: readonly string[] = [
   'en',
   'en-rt',
-  ...FOREIGN_LANGUAGES.flatMap(language => [language, `${language}/up`]),
+  'eng',
+  ...FOREIGN_LANGUAGES.flatMap(language => [language, `${language}/up`, `${language}/eng`]),
 ];
 
 /**
@@ -743,10 +751,14 @@ export const LANES: readonly string[] = [
  */
 const EVAL_BUDGET = 20_000;
 
-/** The upstream surface this uses (`hyperscript.org`'s ESM default export). */
-interface UpstreamEngine {
+/** What a lane needs of a host that reads scripts off attributes: upstream, or the new engine. */
+interface ScriptHost {
   parse(source: string): { errors?: Array<{ message: string }> } | undefined;
   processNode(element: Element): void;
+}
+
+/** The upstream surface this uses (`hyperscript.org`'s ESM default export). */
+interface UpstreamEngine extends ScriptHost {
   internals: {
     runtime: { unifiedEval(parseElement: unknown, context: unknown): unknown };
   };
@@ -809,6 +821,9 @@ export async function initMatrixEngines(): Promise<MatrixEngines> {
   const require = createRequire(import.meta.url);
   const esm = require.resolve('hyperscript.org').replace(/[^/\\]+$/, '_hyperscript.esm.js');
   const upstream: UpstreamEngine = (await import(pathToFileURL(esm).href)).default;
+  const engineModule = await import('@hyperfixi/engine');
+  engineModule.register(...engineModule.everything);
+  const engine: ScriptHost = engineModule.api;
 
   // The evaluation budget: every upstream evaluation goes through unifiedEval.
   const runtime = upstream.internals.runtime;
@@ -862,20 +877,21 @@ export async function initMatrixEngines(): Promise<MatrixEngines> {
   };
   const read = (): string => document.getElementById('out')?.textContent ?? '✗no #out';
 
-  /** Run English on upstream. */
-  const onUpstream = (source: string): string => {
-    const errors = upstream.parse(source)?.errors ?? [];
+  /** Run English on a host that reads the script off the button. */
+  const onHost = (host: ScriptHost, source: string): string => {
+    const errors = host.parse(source)?.errors ?? [];
     if (errors.length) return `✗parse: ${errors[0]?.message.split('\n')[0] ?? ''}`;
     const button = reset();
     button.setAttribute('_', source);
     evaluations = 0;
     const before = reportedErrors;
-    upstream.processNode(button);
+    host.processNode(button);
     click(button);
     if (evaluations > EVAL_BUDGET) return '✗budget';
     const got = read();
     return reportedErrors > before && got === '∅' ? '✗threw' : got;
   };
+  const onUpstream = (source: string): string => onHost(upstream, source);
 
   /** Install a compiled handler on hyperfixi, click, and settle. */
   const onHyperfixi = async (ast: Ast): Promise<string> => {
@@ -914,6 +930,7 @@ export async function initMatrixEngines(): Promise<MatrixEngines> {
       lanes['en-rt'] = await guard(() =>
         english ? onUpstream(render(english, 'en')) : '✗untranslatable'
       );
+      lanes.eng = await guard(() => onHost(engine, cell.source));
 
       for (const language of FOREIGN_LANGUAGES) {
         if (cell.skip?.includes(language)) continue;
@@ -926,6 +943,7 @@ export async function initMatrixEngines(): Promise<MatrixEngines> {
         if (code === null) {
           lanes[language] = '✗untranslatable';
           lanes[`${language}/up`] = '✗untranslatable';
+          lanes[`${language}/eng`] = '✗untranslatable';
           continue;
         }
         const translated = code;
@@ -934,7 +952,15 @@ export async function initMatrixEngines(): Promise<MatrixEngines> {
           if (!compiled.ok || !compiled.ast) return '✗compile';
           return onHyperfixi(compiled.ast);
         });
-        lanes[`${language}/up`] = await guard(() => onUpstream(preprocess(translated, language)));
+        // The adapter's English, once, for both hosts.
+        const adapted = await guard(() => preprocess(translated, language));
+        const up = (lanes[`${language}/up`] = adapted.startsWith('✗')
+          ? adapted
+          : await guard(() => onUpstream(adapted)));
+        lanes[`${language}/eng`] =
+          adapted.startsWith('✗') || up === '✗budget'
+            ? up
+            : await guard(() => onHost(engine, adapted));
       }
       return result;
     },
@@ -966,8 +992,9 @@ export async function runValueMatrix(cells: readonly MatrixCell[]): Promise<Cell
 
 export interface BaselineEntry {
   /**
-   * The failing lanes, space-separated, in LANES order, with two shorthands:
-   * `*direct` for all 23 languages on hyperfixi, `*up` for all 23 on upstream.
+   * The failing lanes, space-separated, in LANES order, with three shorthands:
+   * `*direct` for all 23 languages on hyperfixi, `*up` for all 23 on upstream,
+   * `*eng` for all 23 on the new engine.
    */
   lanes: string;
   /** Where the loss sits, for reading the burn-down (see familyOf); not asserted. */
@@ -989,6 +1016,7 @@ export interface ValueMatrixBaseline {
 
 const DIRECT_LANES: readonly string[] = FOREIGN_LANGUAGES;
 const ADAPTER_LANES: readonly string[] = FOREIGN_LANGUAGES.map(language => `${language}/up`);
+const ENGINE_LANES: readonly string[] = FOREIGN_LANGUAGES.map(language => `${language}/eng`);
 
 /** Lanes (in LANES order) as a baseline string, with a shorthand for each full group. */
 export function compressLanes(lanes: readonly string[]): string {
@@ -996,14 +1024,17 @@ export function compressLanes(lanes: readonly string[]): string {
   const out: string[] = [];
   const direct = DIRECT_LANES.every(l => set.has(l));
   const adapter = ADAPTER_LANES.every(l => set.has(l));
+  const engine = ENGINE_LANES.every(l => set.has(l));
   for (const lane of LANES) {
     if (!set.has(lane)) continue;
     if (direct && DIRECT_LANES.includes(lane)) continue;
     if (adapter && ADAPTER_LANES.includes(lane)) continue;
+    if (engine && ENGINE_LANES.includes(lane)) continue;
     out.push(lane);
   }
   if (direct) out.push('*direct');
   if (adapter) out.push('*up');
+  if (engine) out.push('*eng');
   return out.join(' ');
 }
 
@@ -1013,6 +1044,7 @@ export function expandLanes(text: string): string[] {
   for (const token of text.split(' ').filter(Boolean)) {
     if (token === '*direct') out.push(...DIRECT_LANES);
     else if (token === '*up') out.push(...ADAPTER_LANES);
+    else if (token === '*eng') out.push(...ENGINE_LANES);
     else out.push(token);
   }
   return out;
@@ -1031,7 +1063,10 @@ export function failingLanes(result: CellResult): string[] {
  *                    translation inherits the loss;
  *   - `translation`  some foreign lanes, on both engines;
  *   - `direct-path`  hyperfixi's foreign lanes only;
- *   - `adapter`      upstream's foreign lanes only.
+ *   - `adapter`      upstream's foreign lanes only;
+ *   - `engine`       the new engine differs from upstream on the same text:
+ *                    its English run, or a language's `/eng` lane without
+ *                    its `/up` lane.
  *
  * Several can hold at once; they are joined in that order.
  */
@@ -1048,6 +1083,9 @@ export function familyOf(lanes: readonly string[]): string {
     if (direct.length > both.length && !set.has('en')) parts.push('direct-path');
     if (adapter.length > both.length) parts.push('adapter');
   }
+  if (set.has('eng') || FOREIGN_LANGUAGES.some(l => set.has(`${l}/eng`) !== set.has(`${l}/up`))) {
+    parts.push('engine');
+  }
   return parts.join('+') || 'none';
 }
 
@@ -1082,7 +1120,7 @@ export const ACCEPTED: ReadonlyArray<{
       'increment|#a.textContent + 2',
       'increment|#a.textContent as Int',
     ],
-    lanes: 'it it/up',
+    lanes: 'it it/up it/eng',
     reason:
       'ambiguity: it `di` is both `by` and `of`, so `incrementare i di #a.textContent` also says `increment i of #a.textContent`',
   },