@hyperfixi/engine 7.5.0 → 7.6.0

package/CHANGELOG.md

@@ -7,6 +7,130 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [7.6.0] - 2026-11-10
+
+The engine takes extensions: upstream's `tailwind` and `socket` load from a script tag or
+`register(...)`, and the Vite plugin bundles them. Spanish and Portuguese handlers agree with their
+event (`a la entrada`, `à mudança`), and German writes an event as the noun it is (`wenn Klick`).
+A minor: new features, and renders that change in es, pt and de; everything written before still
+reads.
+
+### Added
+
+- **`@hyperfixi/vite-plugin`: `extensions: ['socket', 'tailwind']`.** The generated bundle
+  imports each `@hyperfixi/engine/ext/<name>` and registers it after the modules, and the dev
+  `everything` fallback does too. Extensions are opt-in, so the scan never adds one. A project
+  that lists an extension gets an engine bundle even when the scan found nothing else (a page
+  whose only hyperscript is a `socket`).
+  - **Which module comes with `toggle` is now read from the grammar.** The plugin used to have
+    the rule "`toggleElement` comes with `toggle`" written in; it now reads which modules add
+    a reading to a command (`Grammar.fallbacks`).
+  - **`verify:reference` checks the engine's extensions as its own.** It registers each
+    `dist/ext/<name>.esm.js`, documents their keywords like the engine's, and parses their
+    examples: `socket`'s hover example is now checked, where it was skipped as "upstream's".
+
+- **`@hyperfixi/engine`: extensions that a script tag can load.** After `hyperfixi-hs.js`, a page
+  can load `ext/<name>.js`, which registers its module with the page's engine. Or, from ESM,
+  `register(...everything, tailwind)` with `@hyperfixi/engine/ext/tailwind`.
+  - **The first extension is upstream's `tailwind`** (the `twDisplay`, `twVisibility` and
+    `twOpacity` hide/show strategies), and upstream's 12 tests for it are now in the engine's
+    gate: 1,434 of 1,498.
+  - **The public object gains `register` and `extensions`, and the script-tag bundle's also gains
+    `kit`.** `register` adds modules. `extensions` lists the extension files the page has
+    loaded. `kit` holds what a module may call: the same names the library entry exports for
+    module authors. Only `hyperfixi-hs.js` carries the kit, so a bundle built from ESM (the Vite
+    plugin's) keeps only the parts of the engine it uses; it registers extensions from ESM, and an
+    extension file loaded beside it says so.
+  - **`register` skips a module it has already added.** When it does add one, it reads again
+    the elements whose scripts failed to parse, so an `async` or late-loaded extension still
+    applies.
+  - **Upstream's own `ext/tailwind.js` also runs on the engine unchanged**, through `use`.
+- **`@hyperfixi/engine/ext/socket`: upstream's `socket` feature.** `socket Chat ws://… [with
+timeout n] [on message [as JSON] …] end` defines `Chat`, a WebSocket with `raw`,
+  `dispatchEvent` (`send ping to Chat` sends the event as JSON) and an `rpc` proxy
+  (`Chat.rpc.f(…)` returns a promise for the reply).
+  - **Upstream's 16 socket tests pass:** the suite is 1,450 of 1,498, with 48 known failures.
+  - **Two differences from upstream:** the socket opens when the feature is installed, not
+    when it is parsed, so a parse alone opens nothing; and with `as JSON` a message that is
+    JSON `0`, `false` or `null` is that value, where upstream rejects it.
+  - **The kit grows to what a feature needs:** `dotOrColonPath`, `urlOrExpression`,
+    `evalStatic`, `commandList`, `makeContext`, `runList` and `assignToNamespace`. Each is
+    exported from `@hyperfixi/engine` and carried on `hyperfixi-hs.js`'s `_hyperscript.kit`.
+
+### Changed
+
+- **`@lokascript/semantic`: a Spanish or Portuguese handler's head agrees with its event, and
+  German writes an event as a noun.** Renders only; everything written before still reads.
+  - **es, pt:** `al` and `ao` hold the masculine article, and were written before every event
+    (`al entrada agregar .a`, `ao mudança de #search …`). A feminine event takes `a la` and `à`:
+    `a la entrada agregar .a`, `à mudança de #search disparar envio em #form`. The first event of
+    an `or` decides; an infinitive (`al redimensionar`) and a custom name (`al my:event`) keep the
+    masculine. Each profile lists its feminine event words (`eventHandler.feminineEventMarker`).
+    es reads `a la` as the head only before one of them, so `poner x a la` is still a put into a
+    variable named `la`. pt's `à` joins its letters and prepositions.
+  - **de:** an event's word takes its capital wherever a command names one: `wenn Klick`,
+    `wenn Änderung von #search auslösen Absenden auf #form`, `warten Änderung`. An event with no
+    German word stays code (`wenn keyup`). The event table lists each one-word name both ways, so
+    `wenn klick` and `wenn doppelklick` read as before.
+
+- **`@hyperfixi/engine`: a module can add a reading to a command without changing what the
+  command reads (`Grammar.fallbacks`).** A fallback registered for a keyword is tried, from just
+  after the keyword, only when the command's own rule fails to parse, and it counts only if it
+  reads at least as far as that rule got. `toggle <element>` (the `toggleElement` module) is now
+  one. Every `toggle` that upstream reads now goes through upstream's rule exactly (registering
+  `toggleElement` used to send every `toggle <target>` through a different expression rule).
+  An unfinished upstream `toggle` now reports upstream's error: `toggle #d as` used to say
+  `Expected 'modal'`, and now says `Expected dotOrColonPath`, as upstream does. The
+  `Grammar.toggleElement` slot is gone; a module that set it registers a fallback instead.
+  `Parser` gains `mark()` and `reset()`.
+
+### Fixed
+
+- **`@lokascript/semantic`: a translated `socket` comes back as the socket upstream reads.**
+  A socket's `on message [as JSON] …` is its own clause, closed by the socket's one `end` (or
+  by the end of the script). Semantic read it as an event handler, eventsource's shape, so:
+  - a clause closed by `end` came back with a second `end`, in every language. The engine
+    rejects that, so a translated socket failed to parse on the page;
+  - a clause with no `end` (upstream's tests write them that way) lost its body, and a
+    clause's `as JSON` was read as leftover input. `translate` refused both;
+  - a dotted name came back split: `socket MyApp.chat …` became `socket MyApp .chat …`, a
+    different socket.
+
+  `as JSON` is now written with the language's own word for `as`, as a conversion is (es
+  `como JSON`, ja `として JSON`). Text semantic wrote before, with two `end`s, still reads as
+  the one socket it was.
+
+  Where a language puts its handler word after the event (ja `messageで`, tr `message da`), a
+  socket or eventsource whose body starts with a word that looks like an event (ja
+  `messageで messageを 記録`, "on message log message") now reads. The handler word used to
+  be taken as the start of the body.
+  - **Measured by the command-shape gate, which now reads extension syntax.** Its engine
+    registers every extension the engine builds. Its harvest reads upstream's `ext/` tests,
+    and the scripts a test writes as `textContent` (how upstream's socket tests write theirs).
+    That adds 33 cases (1,168 in all), and each passes in all 24 lanes. Before this fix, 4 of
+    the 16 socket cases were refused in every language and 1 was silent in every language.
+
+## [7.5.1] - 2026-10-23
+
+The last two silent misreads of hand-written non-English hyperscript that the 7.3.0 live test
+found: one is now refused, the other reads right.
+
+### Fixed
+
+- **ko: an event word followed by its object particle is the verb's object, not a handler.** At
+  top level, hand-written `로드 를 대기` (wait for load) read as `on load wait 를`: a handler on
+  `load` waiting on a variable named `를`, and translate() did not refuse it. Top level is now
+  refused, as ja `ロード を 待つ` and tr `yükleme i bekle` already were; inside a handler,
+  `클릭 할 때 로드 를 대기` still reads `wait for load`. ko's own render of
+  `trigger click on #btn …` (`#btn에 클릭을 트리거 …`) had been refused for the same reason and now
+  translates.
+- **es `eso`, `esto` and a detached `lo` read as `it`, as do pt `isto` and fr `cela`/`ceci`.**
+  `poner eso en #o` read `put eso into #o`, a variable nobody set, with no error. Most profiles
+  already write `it` as a demonstrative (pt `isso`, fr `ça`, ru `это`, he `זה`, ja `それ`). What
+  `it` renders to is unchanged. A variable spelled like one of these words now reads as `it` in
+  that language, as one named `isso` already did in pt; MCP `translate_code` reports it
+  (`NAME_COLLISION`) with a rename.
+
 ## [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

package/README.md

@@ -39,15 +39,22 @@ feature, or an optional expression kind. A rule that is not registered does not
 script that uses it fails with a parse error that names the token. `src/bundles/full.ts` is the
 list of every module.
 
+A module can also add a reading to a command another module defines, for syntax upstream does
+not have: a fallback (`(g.fallbacks.toggle ??= []).push(rule)`). It is tried from just after the
+keyword, and only when the command's own rule fails to parse. Its reading counts only if it
+reads at least as far as that rule got before failing; otherwise the rule's error stands. So a
+fallback cannot change what the command reads. `toggle <element>` (`src/additions.ts`) is one.
+
 A module can live in another package. `@hyperfixi/speech` is one (upstream's `speak`): it imports
 `expr` and the `Grammar` / `Cmd` / `Expr` types from here, sets `g.commands.speak` to a rule that
 reads its operands off the `Parser` it is handed, and returns a node whose `run` may return a
-promise. `register(...everything, speak)` builds an engine with it. (The script-tag bundle is a
-fixed list; nothing adds a module to a page's `hyperfixi-hs.js` after it loads.)
+promise. `register(...everything, speak)` builds an engine with it. What a module may call is
+`src/kit.ts` (below); `register` skips a module it has already added.
 
 The public object is shaped like upstream's `_hyperscript` (`evaluate`, `parse`, `process`,
 `config`, `use(plugin)`, `addBeforeProcessHook`), so a plugin written for upstream's public API
-can be used on it; the multilingual adapter is. It adds one hook upstream lacks:
+can be used on it; the multilingual adapter is, and so is upstream's own `ext/tailwind.js`,
+unchanged. It adds a hook upstream lacks:
 
 ```ts
 _hyperscript.addSourceTransform((source, element) => english);
@@ -55,7 +62,55 @@ _hyperscript.addSourceTransform((source, element) => english);
 
 A script is rewritten as it is read. The element keeps the text its author wrote, and a parse
 error in the rewritten script carries that text (`error.written`). `@lokascript/hyperscript-adapter`
-uses the hook when the host has it.
+uses the hook when the host has it. It also adds `register` and `extensions`, and in the
+script-tag bundle `kit`, for extensions (next).
+
+### Extensions
+
+An extension is a module that is not in `everything`. It is added with `register`: from ESM, or
+on a page, after the script-tag bundle, by its own file:
+
+```html
+<script src="hyperfixi-hs.js"></script>
+<script src="ext/tailwind.js"></script>
+```
+
+```ts
+import { register, everything } from '@hyperfixi/engine';
+import { tailwind } from '@hyperfixi/engine/ext/tailwind';
+register(...everything, tailwind);
+```
+
+With `@hyperfixi/vite-plugin`: `hyperfixi({ extensions: ['tailwind'] })`. The plugin's scan
+never adds an extension; a project lists the ones it uses.
+
+- **What a module may call is `src/kit.ts`**: for parsing, `expr`, `dotOrColonPath`,
+  `urlOrExpression`, `evalStatic` and `commandList`; for running, `makeContext`, `runList` and
+  `assignToNamespace`; and `config`. ESM gets
+  it from the library entry; the script-tag bundle (`hyperfixi-hs.js`) carries it as
+  `_hyperscript.kit`, so an extension file calls the page's engine instead of carrying a copy
+  of its parser. Only that bundle carries it: on every bundle's `api` it would keep the kit's
+  functions in a bundle that uses none of them (~0.25 KB gzipped on a small one, measured), so
+  a bundle built from ESM (the Vite plugin's) registers extensions from ESM. An extension's value
+  imports come from `../kit` only, and the build fails on any other. A name is added to the
+  kit when an extension needs it, as a change to the public API.
+- **An extension file** (`dist/ext/<name>.js`, built from `src/ext/<name>.ts`) registers its
+  module once per page (it records its name in `_hyperscript.extensions`, so a script htmx
+  boost runs again does not register twice), and says so on the console when no engine, or
+  one without the kit, was loaded before it. `dist/ext/<name>.esm.js` is the same module for ESM
+  (`@hyperfixi/engine/ext/<name>`), taking the kit from `@hyperfixi/engine`.
+- **Loaded late** (`async`, a lazy import, a page's own `register` call), an extension still
+  applies: `register` reads again, and only again, the elements whose scripts failed to parse.
+  An extension that claims only what upstream rejects cannot change a script that parsed. A
+  dialect (an extension that changes what a parsed script means) has to be registered before
+  the document is read.
+- **Which extensions there are**, both upstream's and each held to upstream's own tests for it:
+  `tailwind` (the `twDisplay`, `twVisibility` and `twOpacity` hide/show strategies) and
+  `socket` (`socket Chat ws://… [on message [as JSON] …] end`: a WebSocket as a named object
+  with `raw`, `dispatchEvent` and an `rpc` proxy). Here the socket opens when the feature is
+  installed; upstream's opens when it is parsed (`tests/extensions.js` holds the difference). An extension ported
+  from upstream is held to upstream's tests; one of this repository's own will be held to
+  `check:claims`, as the additions are.
 
 ### htmx and fixi
 
@@ -85,10 +140,12 @@ whenever htmx loads.
 | `src/reactivity.ts`, `src/templates.ts`, `src/live-templates.ts` | Optional: `when` / `live` / `bind`; `render` and template text; live templates                                                                               |
 | `src/commands/*`                                                 | 52 command keywords, one module export each                                                                                                                  |
 | `src/additions.ts`                                               | The two forms upstream does not have: `new X()` and `toggle <element>`                                                                                       |
+| `src/kit.ts`, `src/ext/*`                                        | What an extension module may call; the extensions, each built to `dist/ext/<name>.js` (script tag) and `.esm.js`                                             |
 | `src/bundles/*`                                                  | Browser bundle entries. `hyperfixi-hs` is the script-tag bundle; `full` is the same modules, for the gate; `core`, `minimal`, `common` exist to measure size |
 | `upstream-suite/`                                                | The acceptance gate: upstream's Playwright suite (vendored) against a bundle                                                                                 |
-| `tests/`                                                         | This package's own tests (`src/additions.ts`, and regressions upstream's tests did not show), in the form of upstream's and on the same fixtures             |
+| `tests/`                                                         | This package's own tests (`src/additions.ts`, extensions, and regressions upstream's tests did not show), in the form of upstream's and on the same fixtures |
 | `tools/probe.mts`                                                | One source on this engine and on upstream, side by side, on the value matrix's fixture                                                                       |
+| `tools/claims.mts`, `tests/claims.json`                          | What each addition claims, read and run on upstream: the tier each addition may have                                                                         |
 
 A node is typed data plus the closure that runs it, bound when the node is parsed: an
 expression has `ev`, a command has `run`, a feature has `install`. Control flow is a value a
@@ -101,6 +158,7 @@ npm run build --prefix packages/engine          # dist/: library, bundles, decla
 npm run typecheck --prefix packages/engine
 npm run test:upstream --prefix packages/engine  # the gate (needs a build; about 30 s)
 npm run test:own --prefix packages/engine       # additions and regressions (needs a build; 2 s)
+npm run check:claims --prefix packages/engine   # what each addition claims, on upstream (3 s)
 npm run cost --prefix packages/engine           # what each module costs in the full bundle
 
 # Any engine bundle can be scored on the same suite:
@@ -120,15 +178,32 @@ release 0.9.93, the one this repository's other gates use) against `dist/full.js
 that fail must be exactly the ones listed in `upstream-suite/known-failures.json`. A new failure
 fails the gate. So does a listed test that now passes: prune it with
 `npm run test:upstream:update` in the same change, so the list stays what does not pass. CI runs
-it in the `browser-tests` job.
-
-**The package's own tests.** `test:own` runs `tests/` against the same bundle, for the two forms
-upstream has no tests for. Every one must pass. On upstream's own bundle 2 of the 21 pass (the
-two that check an upstream form still reads as it did), which is what shows the rest test the
-additions. `tests/regressions.js` holds the other kind: places where this engine differed from
+it in the `browser-tests` job. The engine the tests run carries the extensions this engine
+builds (`src/ext/`), as upstream's own test bundle carries its extensions (`test/entry.js`):
+the bundle, then each `ext/<name>.js` next to it, as one file. (For upstream's bundle those
+are upstream's own files.) The package's own tests run on the engine alone.
+
+**`test:upstream:update` does not retry**, so a timing flake in its run becomes a listed
+failure. Diff the `failing` list it writes before committing it.
+
+**The package's own tests.** `test:own` runs `tests/` against the same bundle, for what
+upstream has no tests for: the two forms, and the extension tier (`tests/extensions.js`). Every one must pass. On upstream's own bundle 3 of `additions.js`'s 27 pass (the
+three that check an upstream form still reads, or fails, as it did), which is what shows the
+rest test the additions. `tests/regressions.js` holds the other kind: places where this engine differed from
 upstream and upstream's tests did not show it (each of those passes on upstream). CI runs both
 after the upstream suite.
 
+**The claims.** `check:claims` (`tools/claims.mts`) asks what each addition takes from upstream.
+`tests/claims.json` lists, per addition, the sources it gives a meaning to; each is read and
+run on upstream, and the worst outcome sets the tier the addition may be listed with:
+an **addition** claims only what upstream rejects, a **trap repair** also what upstream reads
+but cannot run, a **dialect** something that runs on upstream. The listed tier must be the
+measured one, the engine must read and run every claim, and the engine without the addition
+must read each claim as upstream does (otherwise the claim is not the addition's). A claim
+whose run needs an API jsdom lacks (`showModal`, `togglePopover`) is only read, with the
+reason listed; `tests/additions.js` runs it in Chromium. `--report` prints every claim and
+what each reader did with it.
+
 **The multilingual gates**, in the packages that own them:
 
 - The value matrix (`packages/testing-framework`, `value-matrix.ts`) has an `eng` lane, the
@@ -200,14 +275,16 @@ engine want `increment #count's textContent`. The examples write the second, whi
 bundle runs to the same count (the bundle matrix's Counter row).
 
 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.
+`ext/hs-include.js`, 19), which the first vendoring left out. The engine failed 10 of them until
+it had upstream's htmx integration; it passes all 19. Since 2026-10-25 it also runs upstream's
+tests for each extension this engine builds (`ext/tailwind.js`, 12; see Extensions), so the
+whole suite is 1,498; and the socket tests (`features/socket.js`, 16), vendored from the
+start, pass since the engine builds `socket`.
 
-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.
+The 48 known failures: upstream's internal-API surface (`internals.tokenizer`,
+`evalStatically`, source info, error collection: 45), the worker feature (1: upstream's
+extension, 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.
 
 As a host for the multilingual text path (semantic renders a translation, the adapter's
 `preprocess` turns it back into English, the engine runs the English):
@@ -262,30 +339,32 @@ two values and inserts nothing. The comparison that counts is the DOM a handler
 
 ## Differences from upstream
 
-Three, all recorded here and nowhere silent.
+In syntax, two, both recorded here and nowhere silent.
 
 **Two additions** (`src/additions.ts`, decided 2026-10-01), forms `packages/core` has and the
-shipped examples use. Each is its own module, and neither changes how an upstream script reads:
-upstream's suite passes the same tests with them registered as without.
+shipped examples use. Each is its own module; upstream's suite passes the same tests with them
+registered as without, and `check:claims` measures what each takes from upstream (above).
 
 - `new Date()`, `new Intl.NumberFormat('en')`, `(new Date()).getDay()`: a constructor call as
   an expression. `new` is still an ordinary name unless a constructor call follows it. Upstream
-  has the `make a Date` command and no expression. 0.20 KB.
+  has the `make a Date` command and no expression. 0.20 KB. Measured a **dialect**: upstream
+  reads `set d to new Date()` as `set d to new` (an unset variable) and a second command,
+  `Date()`, which runs and leaves `d` null. With a class (`new Map()`) or a call after it
+  (`new Date().getDay()`, the form the shipped examples use), upstream's reading fails when
+  run instead; inside `put … into` or parentheses, upstream rejects it.
 - `toggle #dialog`, `toggle #dialog modal` (or `as modal`), `toggle #details`: open what is
   closed and close what is open, for a dialog, a details element (or its summary), a popover
   and a select. Upstream rejects `toggle <expression>` unless `between` follows; that form is
-  unchanged. 0.21 KB.
+  unchanged. 0.21 KB. Measured an **addition**: upstream rejects every form it claims. It is
+  a fallback for `toggle` (above), so it reads only what upstream's rule rejects.
 
-**One looser reading**, found by the measurement above: `my @id as String` (an attribute read
-through `my` / `its` / `your`, then a conversion or any further access). Upstream rejects it,
-because its attribute-access rule does not continue the expression chain as every other access
-does; the possessive form `#a's @title as String` works on both. This engine continues the
-chain. It is kept because the stricter reading looks like an upstream slip and a shipped
-example uses the form (`its @data-stock as Number > 0`).
+An attribute read through `my` / `its` / `your` takes nothing after it here, as on upstream:
+both reject `my @id as String` (upstream's attribute-access rule does not continue the
+expression chain); the possessive `#a's @title as String` works on both.
 
 Considered and not added: core's `swap` strategies (upstream's `swap` means something else),
 `copy`, a `? :` conditional, `.debounce(n)`, `has`, prefix `unless`, `set @a to v on <target>`,
-`sorted by … desc`. `push url` / `replace url` are undecided.
+`sorted by … desc`, `push url` / `replace url` (pages write `call history.pushState`).
 
 ## Where the bytes are
 

package/dist/additions.d.ts

@@ -2,13 +2,17 @@
  * Syntax upstream `_hyperscript` does not have. Everything else in this engine
  * follows upstream's source; these two forms come from `packages/core`, are used
  * by the examples this repository ships, and were kept by decision (2026-10-01).
- * Each is an optional module, and neither changes how an upstream script reads:
+ * Each is an optional module. What each takes from upstream is measured, claim by
+ * claim, by `npm run check:claims` (`tests/claims.json`):
  *
  * - `construct`: `new Date()`, `new Intl.NumberFormat('en')`. Upstream has the
  *   `make a Date` command and no expression; there, `set t to new Date().getDay()`
- *   parses (`new` is a variable, the call a second command) and fails when it runs.
+ *   parses (`new` is a variable, the call a second command) and fails when it runs,
+ *   and `set d to new Date()` runs and leaves `d` null. A dialect, kept in every
+ *   bundle by decision (2026-10-25).
  * - `toggleElement`: `toggle #dialog`, `toggle #dialog modal`, `toggle #details`.
- *   Upstream rejects `toggle <expression>` without `between`.
+ *   Upstream rejects `toggle <expression>` without `between`. A fallback for
+ *   `toggle` (`Grammar.fallbacks`), so it reads only what that rule rejects.
  */
 import type { Cmd, Expr } from './ast';
 import type { Grammar } from './parser';
@@ -26,5 +30,8 @@ export interface ToggleElementNode extends Cmd {
     /** `toggle #d modal` / `toggle #d as modal`: open with `showModal()`. */
     modal: boolean;
 }
-/** `toggle <element> [modal | as modal]`: the form `toggle` takes when no `between` follows. */
+/**
+ * `toggle <element> [modal | as modal]`: a fallback for `toggle`, so it reads only what
+ * upstream's rule rejects. It declines a target `between` follows: that is upstream's form.
+ */
 export declare function toggleElement(g: Grammar): void;