@hyperfixi/patterns-reference 3.1.1 → 3.3.0

package/CHANGELOG.md

@@ -7,6 +7,189 @@ 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
+`translate()`, `@lokascript/hyperscript-adapter`, MCP `translate_code` and hyperfixi's
+non-English path now keeps whole programs that it used to shorten or drop: values,
+conditions, loops and handler heads. Every value shape in a generated matrix of 4,205
+(executed in 24 languages, directly and through the adapter, against upstream
+\_hyperscript) now matches upstream, apart from two documented differences. Core
+matches upstream \_hyperscript on more forms.
+
+### Added
+
+- **Counted loops are written in each language's own words**: es `repetir 3 veces`,
+  fr `répéter 3 fois`, ja `3 回 を 繰り返し`, hi `3 बार को दोहराएं`, where translations
+  wrote English `times` in 18 languages and English `repeat` in the SOV six. English
+  `times`/`repeat` and each language's other count words (es `vez`, ru `раза`, …) still
+  read. 18 i18n dictionaries gain a `temporal.times` word.
+- **Variable names that are words of the target language.** A variable spelled like a
+  structure word (es `si`, pl `w`, tr `al`) is written in parentheses, `(si)`, where the
+  plain translation would be misread, and read back as the variable. The language server
+  warns (`name-collision`, with a rename quick fix), MCP `validate_hyperscript` reports
+  `NAME_COLLISION`, and `translate_code` warns when a variable reads as a value word in
+  the target (tl `ako` is `me`). `@lokascript/semantic` exports `nameCollision`,
+  `findNameCollisions` and `findTranslationCollisions`.
+- Event-handler modifiers (`once`, `debounced at`, `throttled at`, `from`) render in every
+  language and are scored by the fidelity signals.
+- `of`-paths and pseudo-commands (`reset() the closest <form/>`) survive translation.
+- `@lokascript/hyperscript-adapter`'s host gate also rejects a translation that reads a
+  reference as a handler's event (`on click on me toggle .active`, an empty click handler
+  plus a handler for an event named `me`), falling back to the author's text with a
+  warning; such a translation used to parse cleanly and do nothing.
+- **Localized htmx attributes: all 23 non-English languages now cover
+  every attribute the _Hypermedia Systems_ book's code listings use** —
+  `hx-vals`, `hx-select`, `hx-swap-oob` and `hx-sync` join the Contact.app
+  twelve (`hx-値`, `hx-valores`, `hx-값`, `hx-werte`, `hx-選択`, `hx-selección`,
+  `hx-seçim`, `hx-auswahl`, `hx-sélection`, `hx-选择`, …). tr/de/fr/zh are new
+  in the table: the Contact.app seven they lacked (`hx-sil`, `hx-löschen`,
+  `hx-supprimer`, `hx-删除`, …) plus audited trigger/swap primaries following
+  loka-js (`hx-tetikleyici`, `hx-auslöser`, `hx-déclencheur`, `hx-替换`; the
+  profile words `hx-tetikle`, `hx-auslösen`, `hx-déclencher`, `hx-交换` still
+  resolve). de gains a lowercase `hx-ziel`: the profile's `hx-Ziel` could never
+  match a parsed attribute, since HTML lowercases attribute names. The other
+  15 languages (ar, bn, he, hi, id, it, ms, pl, qu, ru, sw, th, tl, uk, vi)
+  are unreviewed drafts, every entry flagged `lowConfidence`; they also gain
+  the trigger heads their dictionaries left in English (ms and tl all six,
+  vi/he/ar some). id gains `hx-sasaran` for a target that was the English
+  identity; tl keeps `hx-target` on purpose. `hx-ext` is left in English on
+  purpose: htmx 4 removed it. The vocab table gains an `events` block for
+  trigger heads the i18n dictionaries do not name; ja, es, pt and ko author
+  the DOM `search` event (`検索`, `buscar`, `검색`), which the book's and
+  Contact.app's search box fires. htmx's own trigger words (`revealed`,
+  `every`) stay English, like the `delay:` / `from:` modifiers.
+- Adapter-only vocab keys now resolve from the authored table alone, never
+  from a semantic profile: 22 profiles carry a `select` keyword that means
+  mark/highlight text (de `markieren`, tr `vurgula`), and it would otherwise
+  have shipped as `hx-select` in 22 unreviewed languages.
+
+- **Localized htmx attributes: ja, es, pt and ko now cover every attribute the
+  _Hypermedia Systems_ Contact.app uses** — `hx-post`, `hx-delete`,
+  `hx-confirm`, `hx-push-url`, `hx-boost`, `hx-indicator` and `hx-include` join
+  the existing five (e.g. `hx-削除`, `hx-eliminar`, `hx-excluir`, `hx-삭제`).
+  `hx-indicator` / `hx-include` localize under `@hyperfixi/htmx-adapter` (stock
+  htmx implements them; the embedded layer does not).
+- **Vocab aliases.** Several localized names may map to one attribute or event;
+  the first is the form to teach, later ones keep already-authored pages
+  working. Core's embedded orchestrator now reads whichever form an element
+  carries (it previously kept a single name per attribute).
+
+### Changed
+
+- **Rendered vocabulary** (owner decisions): `null` is written `null` in ar, hi, id, qu,
+  sw, th and tr, where it shared the word for `empty`; hi writes `no` as `कोई नहीं`; qu
+  writes `and` as `hinallataq`; tl and tr write `includes` with `contains`' word (both
+  engines read the two as one operator).
+- `@lokascript/semantic` exports its real `VERSION` (it was `0.1.0` since the first
+  release); browser bundles report `<version>-<bundle>`.
+- MCP `translate_hyperscript` is described accurately: it uses the same semantic engine as
+  `translate_code`, without the verification.
+- **Audited primaries for `hx-trigger` / `hx-swap`** in ja (`hx-トリガー`,
+  `hx-置換`), es (`hx-disparador`, `hx-intercambio`), pt (`hx-gatilho`,
+  `hx-troca`) and ko (`hx-교체`), following loka-js's terminology reviews. The
+  names that shipped before (`hx-引き金`, `hx-disparar`, …) still resolve.
+- The vocab modules are regenerated against the current i18n dictionaries.
+  **No working name was removed** — 141 retired event names and three attribute
+  names are kept as aliases. One name changed meaning with its dictionary: sw
+  `panya_juu` is now `mouseup` (was `mouseover`).
+
+### Fixed
+
+- **Translations that lost code** (semantic parse and render, in every language):
+  - `get` of a literal (`get "hello"`, `get 3`, `get true`) dropped the whole command; an
+    object literal after `get` was cut to `get {`.
+  - Loops keep their extent and body; `repeat until` stops; a loop keeps its index
+    variable, the tail after an `if` inside it, and the command after an empty loop its own
+    `end` closes; a count may be any value (a variable, `$n`, `it`, a possessive), where
+    some translations read `forever`, a silent infinite loop.
+  - Handler heads keep `or` events, filters and event parameters; a translated
+    `wait for <event>` waits instead of throwing; behaviors keep their handlers and init
+    blocks; an else-if chain shares one `end`.
+  - Values keep their comparison phrases (`is equal to`, `includes`, `is an Element`, …),
+    `and`/`or`/`not`, `mod`, possessive and `of` chains, object and array literals, every
+    conversion core supports (`as Int`, `as Fixed:2`, piped conversions), unary minus and
+    property paths; `true`/`false`/`null` keep their meaning.
+  - Commands keep `put … into <variable>`, `tell … to show`, fetch's `do not throw` and
+    response type, event-source/socket URLs, show/hide `with` strategies, `go`/`scroll`
+    positions, `${…}` URLs, core's `has`, and a class query's `in` scope.
+- **`@hyperfixi/core` follows upstream \_hyperscript**:
+  - `X of Y` binds as property access, and the X of a null target is null.
+  - `increment` reads its amount and counter as upstream does, and writing an object's
+    property through `'s`/`of` works.
+  - A loop's count reads as upstream's `index < times` does: `"6.5"` loops 7 times and
+    `"6abc"` none, in the full runtime and in the hybrid bundles (`hyperfixi-hx.js`,
+    plugin bundles), which read `parseInt`.
+  - Blocks close at the end of input; `morph … to`; `render … with name: value`; `beep!`
+    as an expression; `transition`'s owners, several properties, `from` and `using`; three
+    handler forms from _Hypermedia Systems_; four upstream-valid forms that compiled and
+    then failed at run time; `.item in #list` keeps its scope; `on click once` fires on
+    the first click.
+- htmx: camelCase event names survive an attribute name.
+- MCP: the validators report what the parsers actually did.
+- The AOT compiler (experimental): loops were compiled to `while (true)`; targets,
+  property access, scoped queries, `empty` and variable scope now compile to what they
+  mean.
+- `@lokascript/hyperscript-adapter` and `@hyperscript-tools/multilingual` READMEs: the
+  Japanese quickstart example was a dead button, and the multi-language example loaded
+  only the Spanish bundle; the examples are now native and run in a test. Bundle sizes are
+  measured.
+- Bare CDN URLs now serve a browser bundle: `unpkg.com/@lokascript/hyperscript-adapter@3` (and
+  jsDelivr) served `dist/index.cjs`, which throws in a `<script>` tag. The adapter,
+  `@hyperscript-tools/multilingual`, `@lokascript/semantic`, `@hyperfixi/core` and
+  `@lokascript/htmx-adapter` declare `unpkg`/`jsdelivr` entries.
+- `hyperfixi-multilingual.js`'s error names the semantic bundle that exists (the full
+  `browser.global.js`, the only one that defines `LokaScriptSemantic`).
+- READMEs: `@lokascript/i18n` no longer claims to translate (and its `/lsp` export and CLI,
+  which do not exist, are gone); `@lokascript/semantic`, `@hyperfixi/vite-plugin` and
+  `@hyperfixi/core` have correct package names, API calls, language lists (24) and measured
+  bundle sizes.
+- Dependencies: the js-yaml and smol-toml advisories; Vite 8, vitest 5 and happy-dom 20.14.
+- **Vietnamese `hx-get` / `hx-target` / `hx-swap` / `hx-trigger` / `sse-swap`
+  never worked**: the names were emitted with spaces (`hx-lấy giá trị`), which
+  HTML reads as three attributes. They are now hyphen-joined
+  (`hx-lấy-giá-trị`), like vi's existing `hx-trực-tiếp`.
+- 29 multi-word event names (ar, vi) were removed from the vocab modules: an
+  event is a single token of an `hx-trigger` value, so they could never match.
+
 ## [3.1.1] - 2026-09-04
 
 ### Fixed
@@ -716,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/README.md

@@ -10,11 +10,16 @@ npm install @hyperfixi/patterns-reference
 
 ## Quick Start
 
-The package ships with a **pre-populated SQLite database** containing:
+The package ships with a **pre-populated SQLite database** — built at publish
+time from the released source, the same database CI's gates judge — containing
+(counts as of 2026-09-25):
 
-- 164 code examples covering hyperscript commands and real-world UI patterns
-- 3,936 translations (164 patterns × 24 languages)
-- 648 LLM few-shot examples for code generation
+- 168 code examples covering hyperscript commands and real-world UI patterns,
+  each with the engine(s) mechanically verified to run it (`engine`: `both`,
+  `lokascript` = hyperfixi, `hyperscript` = upstream _hyperscript)
+- 4,032 translations (168 patterns × 24 languages)
+- ~660 LLM few-shot examples for code generation (an example no engine runs is
+  never served)
 
 No setup required - just install and use:
 
@@ -61,12 +66,20 @@ getPatternsByCategory(category: string): Promise<Pattern[]>
 // Get patterns containing a specific command
 getPatternsByCommand(command: string): Promise<Pattern[]>
 
-// Full-text search across title, code, and description
+// Full-text search across title, code, and description (and, with
+// `language`, that language's translation)
 searchPatterns(query: string, options?: SearchOptions): Promise<Pattern[]>
 
 // Get all patterns (paginated)
 getAllPatterns(options?: SearchOptions): Promise<Pattern[]>
 
+// SearchOptions — every filter applies, then the page (limit/offset):
+//   category    the pattern's category
+//   difficulty  'beginner' | 'intermediate' | 'advanced', inferred from the code
+//   language    patterns usable in that language: a translation that parses
+//               there, or markup with no hyperscript to translate
+//   engine      'hyperscript' | 'lokascript' | 'both', or null for unverified
+
 // Get pattern statistics
 getPatternStats(): Promise<PatternStats>
 ```
@@ -134,8 +147,8 @@ These scripts are for contributors regenerating the database. **End users don't
 | `npm run db:init:force`     | Reinitialize database (overwrites existing)              |
 | `npm run sync:translations` | Generate translations for all 24 languages               |
 | `npm run seed:llm`          | Generate LLM few-shot examples                           |
-| `npm run validate`          | Validate all patterns parse correctly                    |
-| `npm run validate:fix`      | Validate and update verified_parses flag                 |
+| `npm run verify`            | Re-measure `verified_parses` (populate already does)     |
+| `npm run verify:engines`    | Re-verify `engine` on both engines; commit the JSON      |
 | `npm run build`             | Build the package                                        |
 | `npm test`                  | Run tests in watch mode                                  |
 | `npm run test:run`          | Run tests once                                           |
@@ -146,42 +159,43 @@ These scripts are for contributors regenerating the database. **End users don't
 
 Pattern source code from the hyperscript cookbook.
 
-| Column      | Type | Description                           |
-| ----------- | ---- | ------------------------------------- |
-| id          | TEXT | Unique identifier                     |
-| title       | TEXT | Human-readable title                  |
-| raw_code    | TEXT | Hyperscript code                      |
-| description | TEXT | Pattern description                   |
-| feature     | TEXT | Category (e.g., 'class-manipulation') |
-| created_at  | TEXT | Creation timestamp                    |
+| Column      | Type | Description                                                                                                                        |
+| ----------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| id          | TEXT | Unique identifier                                                                                                                  |
+| title       | TEXT | Human-readable title                                                                                                               |
+| raw_code    | TEXT | Hyperscript code                                                                                                                   |
+| description | TEXT | Pattern description                                                                                                                |
+| feature     | TEXT | Category (e.g., 'class-manipulation')                                                                                              |
+| engine      | TEXT | Engines verified to run it: `both`, `lokascript` (hyperfixi), `hyperscript` (upstream), or NULL (neither) — mechanical, CI-checked |
+| created_at  | TEXT | Creation timestamp                                                                                                                 |
 
 ### pattern_translations
 
 Multilingual translations of patterns.
 
-| Column          | Type    | Description                      |
-| --------------- | ------- | -------------------------------- |
-| id              | INTEGER | Auto-increment ID                |
-| code_example_id | TEXT    | Foreign key to code_examples     |
-| language        | TEXT    | Language code (en, ja, es, etc.) |
-| hyperscript     | TEXT    | Translated code                  |
-| word_order      | TEXT    | SVO, SOV, VSO, or V2             |
-| confidence      | REAL    | Translation confidence (0-1)     |
-| verified_parses | INTEGER | Whether translation parses (0/1) |
+| Column          | Type    | Description                                                                                                                          |
+| --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| id              | INTEGER | Auto-increment ID                                                                                                                    |
+| code_example_id | TEXT    | Foreign key to code_examples                                                                                                         |
+| language        | TEXT    | Language code (en, ja, es, etc.)                                                                                                     |
+| hyperscript     | TEXT    | Translated code                                                                                                                      |
+| word_order      | TEXT    | SVO, SOV, VSO, or V2                                                                                                                 |
+| confidence      | REAL    | Translation confidence (0-1)                                                                                                         |
+| verified_parses | INTEGER | 1 when the semantic parser accepts every hyperscript body of the row in its language (measured at sync; says nothing about fidelity) |
 
 ### llm_examples
 
 Prompt/completion pairs for few-shot learning.
 
-| Column          | Type    | Description                  |
-| --------------- | ------- | ---------------------------- |
-| id              | INTEGER | Auto-increment ID            |
-| code_example_id | TEXT    | Foreign key to code_examples |
-| language        | TEXT    | Language code                |
-| prompt          | TEXT    | Natural language prompt      |
-| completion      | TEXT    | Hyperscript code             |
-| quality_score   | REAL    | Quality rating (0-1)         |
-| usage_count     | INTEGER | Retrieval count              |
+| Column          | Type    | Description                   |
+| --------------- | ------- | ----------------------------- |
+| id              | INTEGER | Auto-increment ID             |
+| code_example_id | TEXT    | Foreign key to code_examples  |
+| language        | TEXT    | Language code                 |
+| prompt          | TEXT    | Natural language prompt       |
+| completion      | TEXT    | Hyperscript code              |
+| quality_score   | REAL    | Quality rating (0-1)          |
+| usage_count     | INTEGER | Deprecated: reads never count |
 
 ## Supported Languages
 
@@ -249,9 +263,6 @@ npm run populate
 # Run tests
 npm test
 
-# Validate translations
-npm run validate
-
 # Build
 npm run build
 ```