@hyperscript-tools/i18n 2.7.2 → 2.9.0

package/CHANGELOG.md

@@ -0,0 +1,393 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### ⚠ BREAKING (types)
+
+- **Domain renderers return `string | null`.** `renderSQL`, `renderJSX`, `renderTodo`,
+  `renderLLM`, `renderFlow`, `renderBDD`, `renderVoice` and `renderBehaviorSpec`
+  previously signalled "I don't know this action" with a successful-looking
+  sentinel string — `` `-- Unknown: ${node.action}` `` (or `// Unknown:` in three
+  domains). Consumers were forced into string matching, and any legitimately
+  rendered sentence starting with `--` was silently dropped. They now return
+  `null`.
+
+  **Rendered output for every previously-known action is byte-identical** — all
+  1,939 existing domain tests pass unchanged.
+
+  _Migration:_ replace sentinel sniffing with a null check. A guard of the shape
+  `if (!sentence || sentence.startsWith('--')) return null;` already handles it.
+
+### Added
+
+- **Domains are open for extension** (`@lokascript/framework` + all 8 domain packages).
+  A consumer can add a command to a domain **without editing that package**, by
+  passing a `DomainExtension` to `createXDSL({ extensions })`. A schema plus one
+  vocabulary entry per language is enough to parse, render and compile it in all
+  of them — word order, marker placement and keyword position derive from the
+  schema and the language profiles. Vocabulary may cover a subset of the DSL's
+  languages, so it can be filled in over time. See
+  [Extending an Existing Domain](packages/framework/docs/DOMAIN_AUTHOR_GUIDE.md#extending-an-existing-domain).
+- **`createDomainRenderer`** (`@lokascript/framework`) composes a domain's
+  hand-written per-action renderers with a schema-driven fallback, returning
+  `null` for actions it has neither for. It is what each domain's `renderX` now
+  runs, and what makes an extension command render without the domain knowing it
+  exists.
+- **`MultilingualDSL.render(node, language)`** — render a parsed node back to
+  natural language. Chains extension renderer → domain renderer → schema
+  fallback → `null`. `parse()` + `render()` is the language-to-language path that
+  does not need a `grammarProfile`.
+- **`getAllTranslationsWithStatus()`** (`@lokascript/semantic`) — the same result
+  as `getAllTranslations()`, plus a `failed` map naming each language that could
+  not render and why.
+- **`createMultilingualDSL` is now a named export** of `@lokascript/framework`
+  rather than reaching consumers only through a wildcard re-export. Domains also
+  export `allProfiles`, which extension authors need.
+- **A CHANGELOG now ships in every published package.** Determining what changed
+  between two releases previously meant probing the installed code.
+
+### Changed
+
+- **Directional markers for `add` / `put` / `go` in es, ar, zh, fr, de, pt**
+  (`@lokascript/semantic`). Every language profile's `destination` marker is
+  locative (`on` / `على` / `在` / `sur` / `auf`) because it also serves
+  `toggle`/`show`; only English overrode it for the directional commands, so the
+  rest rendered "add .active ON #box". Now: add → es `a`, ar `إلى`, zh `到`,
+  fr `à`, de `zu`, pt `a`; put → ar `في`, zh `到`, fr `dans`, de `in`; go → es `a`,
+  ar `إلى`, fr `à`, de `zu`, pt `para`. ja `に` / ko `에` / tr `e` were already
+  directional and are unchanged.
+
+  **Parsing accepts a strict superset**: a new `RoleSpec.markerLegacy` keeps every
+  previously-rendered marker parsing, so source written against ≤2.8 keeps working.
+  Downstream consumers maintaining correction tables for these markers (as
+  `lokascript-learn` does) can now delete those entries.
+
+- **`createSchemaRenderer` honors `svoPosition` / `sovPosition`.** It previously
+  iterated roles in declaration order and never read the positions, so a schema
+  whose declared order differed from its declaration order rendered a surface its
+  own generated pattern could not re-parse. It now sorts with the same comparator
+  pattern generation uses (**descending — higher values render earlier**). Affects
+  only custom schemas; no in-repo consumer relied on the old behavior.
+- **Absent roles no longer leave a dangling marker.** `createSchemaRenderer` emitted
+  a role's marker even with no value, producing `analyze #content as` /
+  `#content として 分析`.
+- **`getAllTranslations()` covers every registered language** (24) instead of a
+  frozen 13-language list, and a language that fails to render is skipped rather
+  than throwing. The full browser bundle now registers Hebrew, which was
+  registered everywhere except there.
+- **Schema-validation diagnostics are opt-in.** `import '@lokascript/domain-llm'`
+  printed ~44 lines of `[SCHEMA VALIDATION]` stderr into every downstream test run
+  and CI log. Set `LOKASCRIPT_SCHEMA_VALIDATION=1` to see them; a standing test in
+  `@lokascript/semantic` keeps them honest.
+- **`dsl.translate()` names the missing config field** when a language has no
+  `grammarProfile`, instead of failing deep in the transformer with
+  "No profile found for language: en". Anyone matching that exact message must update.
+- **`defineCommand` / `getRoleSpec` validate their input.** A malformed schema now
+  fails with a message naming the field, instead of
+  `TypeError: undefined is not an object (evaluating 'schema.roles[0]')` from
+  inside the package.
+
+### Fixed
+
+- **A corrected marker stopped parsing in nested contexts.** Three separate
+  override branches — the SOV and VSO event-handler generators and the shared
+  marker resolver — each dropped marker alternatives, so Arabic
+  `ضع هو إلى #chat` parsed standalone but not inside a `socket` block. They now
+  share one definition of what an override still accepts.
+
+## [2.8.0] - 2026-07-25
+
+> **Gap note:** 2.6.0 through 2.7.2 shipped without entries in this file; their
+> details live in [GitHub Releases](https://github.com/codetalcott/hyperfixi/releases).
+> Full notes for this release: `docs-internal/RELEASE_NOTES_v2.8.0-draft.md` (swapped
+> into the GitHub release on publish day).
+
+A size and correctness release: the full bundles shed a duplicated core+semantic copy (~534 → ~299 KB gz), the semantic parser closes out several multilingual correctness arcs, and the publish pipeline's gates are now honest end-to-end.
+
+### Highlights
+
+- **Full bundles nearly halved** (`@hyperfixi/core`): since 2.7.0 the full bundles shipped two copies of the core runtime and multilingual parser (the bundled reactivity/realtime plugins resolved `@hyperfixi/core` to its prebuilt dist alongside the bundle's own source graph). A rollup alias folds everything onto one graph: `hyperfixi.js` ~534 → **~299 KB gz**, `hyperfixi-hx-v4.js` ~540 → **~311 KB gz**. Same features and pre-installed plugins; CI size ceilings ratcheted down to catch re-duplication.
+- **`fetch … with { … }` options in all 24 languages** (#662): request options (braced bodies, `method:` / `headers:` / `body:` named args) are captured by the semantic parser in every supported language — previously most non-English languages silently dropped the clause and issued a bare GET.
+- **Event modifiers in all 24 languages** (#673): `once`, `debounce(N)`, `throttle(N)` and their translated forms flow from every language's event-handler head to the runtime.
+- **Foreign→English canonical validity: 3059/3059** (#724–#732, pick text-range #733/#734/#736): every authored foreign translation now renders English that the canonical hyperscript.org parser accepts — both canonical-validity allowlists are empty — and a new R4 canonical-validity ratchet (#727) plus a ninth `--regression` signal keep it that way.
+- **New package: `@lokascript/htmx-adapter`** (#735): multilingual adapter for upstream htmx v4 (canonicalizing extension).
+
+### Fixed
+
+- **`go to url "/page"` no longer drops the URL** (#680) — the destination was silently lost in every language (the English reference itself was affected, which masked it).
+- **Broken event listeners in six languages** (#681) — de/fr/id/it/pl/zh dictionaries rendered `mousedown`/`mouseup` as words the parser could not resolve; a V3c vocabulary check now verifies every dictionary event word round-trips on the parse side.
+- **"Unknown command: compound" on semantic-path bundles** (#675) — multi-command handler bodies could throw at runtime on the full bundles; the per-segment semantic adapter now defers non-command parses to the traditional parser.
+
+### Infrastructure
+
+- Publish pipeline hardening (#672, #674): reproducible `npm ci` installs, `pre-publish-check` with real exit codes end-to-end, export validation after bundle builds, complete BUILD_ORDER, and a final verdict step that always runs.
+- Vocab consistency gate and total input-coverage instrumentation in CI; the multilingual fidelity ratchet holds the 2026-07-11 high-water marks (fidelity 1.000 on all 3,696 corpus rows across 24 languages).
+
+## [2.5.1] - 2026-05-24
+
+A single-bug patch for a v2.5.0 publishing regression that broke every localized htmx attribute.
+
+### Fixed
+
+- **`hyperfixi-hx.js` / `hyperfixi-hx-v4.js`: `window.__hyperfixi_i18n` lost to terser** (`@hyperfixi/core`). The Phase 8 orchestrator's public-API singleton (`window.__hyperfixi_i18n = { register }`) was being eliminated by terser in the published v2.5.0 hybrid-hx and hybrid-hx-v4 bundles, silently breaking every `vocab/htmx/{lang}.js` module on load with `"loaded before the htmx-compat orchestrator"`. Two layers fixed: (1) the module-level `installPublicAPI()` invocation is now exported and called explicitly from each bundle entry that includes htmx-compat, so terser's `unused: true, toplevel: true` pass can't drop it; (2) the API is exposed via bracket-access (`window['__hyperfixi_i18n']`) to bypass terser's `properties.regex: /^_/` mangling. Localized htmx attribute names (`hx-obtener`, `hx-取得`, `hx-احصل`, …) now resolve correctly in the published bundles, matching their already-working behavior under the source-aliased vitest suite.
+
+### Tests
+
+- **Orchestrator public-API gate** in pre-publish-check + release-smoke. New 2-test Playwright spec (`packages/core/src/compatibility/browser-tests/i18n-orchestrator-api.spec.ts`, ~600 ms) asserts `typeof window.__hyperfixi_i18n.register === 'function'` in both shipped htmx bundles. Wired into `.github/workflows/pre-publish-check.yml` (fails the workflow on regression) and the `--matrix` stage of `examples/release-smoke/run.mjs` (so the gate fires against the registry-installed tarball, not only the locally-built dist). Surgical — no swap-pipeline dependency. The broader `i18n-htmx.spec.ts` remains un-wired pending two pre-existing bugs unrelated to this release: a reactivity / notify-hook bug breaking localized `hx-live` re-renders, and a swap-pipeline bug stringifying `DocumentFragment`s in `fetch ... as html` → `put it into target`.
+
+## [2.5.0] - 2026-05-22
+
+A focused release: a new LLM-domain introspection API, plus correctness fixes for the parser, the multilingual renderers, and how published packages declare their internal dependencies.
+
+### Added
+
+- **`describeCommands()` / `describeCommand()`** in `@lokascript/domain-llm` — a JSON-serializable description of every LLM command: its roles, per-language marker keywords, and a verified runnable example in each of the 8 supported languages. Adds the `LLM_LANGUAGE_CODES` export. One source of truth for docs, MCP tool schemas, and LLM-agent discovery. `@lokascript/domain-llm` also gains a package README.
+
+### Fixed
+
+- **`toggle @attribute`** (`@hyperfixi/core`): `toggle @disabled`, `toggle @required`, and similar threw `toggle command: no valid class names found` in the browser. `toggle` now skips semantic parsing (like its sibling DOM commands `add` / `remove`), so the `@attr` / `.class` / `*property` argument forms all work.
+- **SOV word order in the multilingual renderers** (`@lokascript/domain-bdd`, `@lokascript/domain-llm`): Japanese / Korean / Turkish output from `renderBDD` and `renderLLM` was not parseable — particle placement and word order were wrong, so `translate_bdd` / `translate_llm` produced broken SOV text. Fixed, with render→compile round-trip guardrail tests.
+- **Internal dependency versions**: published packages declared their internal workspace dependencies as `"*"`, which shipped literally to npm and could let a consumer resolve a mismatched (older) internal package. Internal deps now carry exact caret ranges.
+
+## [2.4.0] - 2026-05-20
+
+Two parallel arcs landed since v2.3.1: **upstream `_hyperscript` 0.9.90 parity** (9 phases — commands, comparators, collection ops, event modifiers, plugin system, 3 new public plugin packages, i18n) and **htmx v4 compatibility** (reactive `hx-live`, SSE/WebSocket streaming, per-element localized attribute names, the size-busting `hyperfixi-hx-v4.js` bundle).
+
+### Added
+
+#### Core language (upstream \_hyperscript 0.9.90 compat)
+
+- **9 new commands**: `focus`, `blur`, `empty`, `open`, `close`, `select`, `clear`, `reset`, `breakpoint` — covers DOM focus management, form state, window control, and debugger integration.
+- **4 comparator expressions**: `X starts with Y`, `X ends with Y`, `X is between A and B`, and the postfix `... ignoring case` modifier for case-insensitive string comparison. `between` is inclusive and auto-orders bounds.
+- **5 collection infix operators**: `collection where <pred>`, `collection sorted by <key>`, `collection mapped to <expr>`, `string split by <sep>`, `array joined by <sep>`. `where`/`sorted by`/`mapped to` bind `it` per element for inline predicates/keys.
+- **Event modifiers**: `on first <event>` alias for `.once`, plus synthetic `on resize` for HTMLElements backed by `ResizeObserver` (browser standard `resize` is window-only).
+
+#### Plugin system
+
+- **`HyperfixiPlugin` public API**: `installPlugin(plugin)` on Runtime, `ParserExtensionRegistry` singleton with snapshot/restore for test isolation. Five plugin seams: `registerFeature`, `registerNodeEvaluator`, `registerGlobalWriteHook`, `registerGlobalReadHook`, and `HyperfixiPluginContext.runtime`. `$name` globals canonicalized to bare-key storage across `setVariableValue` and both identifier evaluators.
+
+#### New plugin packages
+
+- **`@hyperfixi/speech`**: Voice I/O via Web Speech API — `speak "text"` (with optional `rate`/`pitch`/`voice`/`volume`), `ask "question"`, `answer with "value"`. Idempotent installation; no-ops cleanly when the Web Speech API or `window.prompt()` is unavailable.
+- **`@hyperfixi/reactivity`**: Reactive signals — `live { ... }` blocks, `bind` expressions (now also accepts explicit property via `'s` or `.` syntax), `when X changes`, `^name` reactive reads. Microtask-flushed scheduler with cycle guard and auto-stop on element disconnect.
+- **`@hyperfixi/components`**: Custom Element registration from `<template component="tag">` / `<script type="text/hyperscript-template" component="tag">`. **v2 shipped this release** — reactive `^var` rendering (via `@hyperfixi/reactivity`), `#if` / `#for` directives, slot substitution, `${expr}` interpolation. Init scripts (`_=` on the `<template>`) run on each stamp.
+
+#### Internationalization (i18n)
+
+- Phase 1 commands translated across all 23 COMPLETE_LANGUAGES (7 new schemas in `@lokascript/semantic`: `empty`, `open`, `close`, `select`, `clear`, `reset`, `breakpoint`).
+- Phase 2 comparators (`starts with`, `ends with`, `between`, `ignoring case`) translated across all 23 languages (with `starts with`/`ends with`/`between` backfills in bn, th, vi).
+- Phase 3 collection ops (`sorted by`, `mapped to`, `split by`, `joined by`) translated across all 23 languages (`where` predated this release).
+- New `packages/i18n/src/schema-alignment.test.ts` — guards drift: every `CommandSchema` must have an `en.ts` entry, Phase 1/2/3 operators must exist across all complete dictionaries.
+
+#### htmx v4 integration
+
+- **`hx-live` reactive expressions**: When `@hyperfixi/reactivity` is installed, the htmx-compat layer recognizes htmx v4's `hx-live` attribute and translates it to a `live ... end` block. The expression body is hyperscript (not JavaScript like upstream htmx v4), so it gets fine-grained dependency tracking + inherits multilingual support. If reactivity isn't installed, the element is skipped with a clear console error.
+- **`sse-connect` / `sse-swap`**: Long-lived `EventSource` per element. Bounded exponential reconnect backoff (1s → 2s → 4s … capped at 30s, 5 retries). Auto-close on DOM removal via `MutationObserver`. Lifecycle events: `htmx:sseOpen`, `htmx:sseMessage`, `htmx:sseError`, `htmx:sseClose`. Multiple named events per connection. Swap targets resolve `closest`/`find`/`next`/`previous`.
+- **`ws-connect` / `ws-send`**: Bidirectional WebSocket per element. JSON envelope routing (`{ target, swap?, data }`) drives surgical updates through the existing `hx-target`/`hx-swap` machinery; raw messages dispatch as `htmx:wsMessage`. Outbound sends queue while connecting, flush on `htmx:wsOpen`. Same reconnect backoff as SSE.
+- **Localized htmx attribute names (Phases 8–10)**: Per-element `lang=` resolution. Authors can write `hx-obtener` / `hx-objetivo` / `sse-conectar` (Spanish), `hx-取得` / `hx-ターゲット` (Japanese), `hx-احصل` / `hx-هدف` (Arabic), etc. — the orchestrator translates them to canonical English before they hit the existing processor. 8 priority vocab modules ship with the bundle (en, es, fr, ja, zh, ar, ko, de). Missing-vocab languages log a one-time warning per language and fall back to English. `eventNameOf` / `selectorFor` / `nameOf` hooks are namespaced (`hx`, `sse`, `ws`) so `hx-on:*` localizes correctly.
+- **htmx event lifecycle**: New CustomEvents `htmx:configuring` (cancelable, mutate `e.detail.config`), `htmx:beforeRequest` (cancelable), `htmx:afterSettle`, `htmx:error`, plus the SSE/WS lifecycle events listed above.
+
+#### Bundles & build tooling
+
+- **`hyperfixi-hx-v4.js`** (~257 KB gz): Full runtime + `@hyperfixi/reactivity` (auto-installed) + htmx-compat + SSE/WS support, all in a single script tag. The "batteries-included" choice for projects using htmx v4 reactive/streaming features. The slim `hyperfixi-hx.js` (~13 KB gz) does NOT ship reactivity/SSE/WS — choose hx-v4 when you reach for `hx-live` / `sse-connect` / `ws-connect`, hx otherwise.
+- **Vite plugin: htmx v4 surface detection** — scans HTML for `hx-live` / `sse-*` / `ws-*` attributes and auto-routes to `hyperfixi-hx-v4.js`; otherwise emits a minimal handcrafted bundle as before.
+- **`getDefaultRuntime()`** exposed for forcing lazy runtime construction (useful for bundles that defer wiring until first DOM event).
+
+### Fixed
+
+- **Runtime**: `it`/`its`/`result` identifier cache no longer returns stale values across loop iterations — required for Phase 3 collection operators that rebind `it` per element (16 ms TTL cache had masked all Phase 3 tests before fix).
+- **Runtime**: method-call `this` binding preserved on member callees — `items mapped to it.toUpperCase()` no longer throws "called on null or undefined". Uses `.apply(thisArg, args)` for member expressions.
+- **Parser**: `is not` binary operator now routes to `notEquals.evaluate` — pre-existing gap where tokens parsed but runtime dispatch threw `Unknown binary operator: is not`.
+- **Runtime**: `execute()` now mutates the caller's `ExecutionContext` in place when injecting the `ExpressionRegistry`, rather than shallow-cloning. Commands writing to `context.result` / `context.it` (e.g. the new `answer` command) now propagate those writes back to the caller — matching the long-standing `context.locals.set(...)` / `context.globals.set(...)` mutation pattern in the same function. `ExecutionContext.registry` is now mutable in the type signature (the runtime is the only legitimate writer; the `readonly` modifier was a defensive holdover from an earlier consolidation arc).
+- **Runtime**: `or` / `and` short-circuit now returns the operand value (truthy/falsy), not a coerced boolean — matches upstream `_hyperscript` semantics.
+- **Runtime**: `put` / `set` / `toggle` accept plain property names as write targets (not just `the X.Y` chains).
+- **Runtime**: `evalHyperScript()` defaults to shared globals when none provided.
+- **Runtime**: scoped `notifyLocalRead()` now fires when reading scoped locals (was missing — broke reactive `bind` to local vars).
+- **Math**: binary-arithmetic operands accept DOM elements (coerced through the consolidated "is this convertible" path).
+- **Parser**: `set the X.Y to Z` dotted property chains (e.g. `set the event.detail.result to ...`) now use the full expression parser rather than a fixed 2-token lookahead — handles arbitrary-depth chains and `of` expressions uniformly.
+- **Parser**: `pick first 3 of arr` and other keyword-led command syntaxes (commands whose argument grammar starts with a keyword) now route through dedicated parsers and preserve trailing args. Added to `COMPOUND_COMMANDS` with a dedicated `parseXxxCommand` per case.
+- **Browser bundle**: `ExpressionRegistry` threaded through the command-execution path (`processCommand` → `adapter.execute` → `parseInput`). Without this, commands like `tell`/`send`/`toggle` whose `parseInput()` evaluates AST nodes failed in the example gallery with "Expression X not in ExecutionContext.registry".
+- **htmx-compat**: `hx-on:*` registers real event listeners directly from the processor (the translator never sees them, so it can stay declarative-only). Refresh observer wired correctly; localized `hx-on:*` prefix resolved via the namespaced i18n hooks.
+- **i18n**: Reactive blocks (`live`, `when X changes`) route around `parseStatement` to fix `when`/`unless` + SOV-language `live` block parsing. Suppressed spurious "then" injection inside live blocks.
+- **patterns-reference**: HTML patterns marked non-translatable (they're DOM markup, not source code); cleaned orphan languages from the database seed.
+- **Semantic**: registry singleton shared across tsup entries (multi-entry split was forking the registry, breaking cross-entry pattern lookups).
+
+### Changed (internal)
+
+- **Evaluator consolidation**: Retired the `BaseExpressionEvaluator` class hierarchy and 4 helper modules (~2,700 LOC removed) in favor of the single canonical evaluator at `parser/runtime.ts:evaluateAST` with the `ExpressionRegistry` on `ExecutionContext`. Both consolidation arcs (α + β) closed.
+- **Domain DSLs**: Extracted a shared config package (`@hyperfixi/domain-config`) consumed by all 8 domain DSLs.
+- **Published infrastructure packages**: `@lokascript/intent`, `@hyperfixi/domain-config`, `@hyperfixi/planner`, and `@hyperfixi/intent-element` are published to npm as transitive dependencies (required for `@hyperfixi/core` and the domain DSLs to install cleanly from the registry). They are infra deps — users do not install them directly. (These were published from post-tag fix-forward commits; the `v2.4.0` git tag predates them.)
+
+## [2.3.1] - 2026-04-23
+
+### Fixed
+
+- **CI**: Added `planner` package to the build step (before `mcp-server`, which depends on it) across `ci.yml`, `publish.yml`, and `pre-publish-check.yml`; added `planner/dist` to the build-artifacts upload.
+- **hybrid-complete bundle**: `toggle @attribute` and positional selectors (`first .x`, `last .y` in selector position) now work — closed a parser gap surfaced by the README "try it live" examples.
+
+### Added
+
+- **README**: "Try it live" link to the gallery, broken-up counter example, tier links.
+
+### Changed
+
+- **`planner` package**: Marked private (workspace-only — published packages should not list private deps).
+
+## [2.3.0] - 2026-03-17
+
+### Added
+
+- **Lazy behavior resolver**: `install X` just works — behaviors resolve on demand without manual registration
+- **Hyperscript-native behaviors**: Behaviors defined as hyperscript source strings via patterns-reference schemas
+- **Dynamic class selectors**: `.{varName}` syntax in `toggle`, `add`, and `remove` resolves variables as CSS class names
+- **Variable/expression durations**: `wait` command now accepts variable and expression durations (e.g., `wait feedbackDuration ms`)
+- **Behavior schema sources**: Single source of truth for behavior schemas in patterns-reference
+
+### Fixed
+
+- **Parser**: `js()` single-quote parsing, `set the X.Y` dotted property chains (e.g., `event.detail.result`), improved `set` error messages
+- **Parser**: Namespaced events (`custom:activate`) and `trigger`/`on` inside `repeat` blocks in behaviors
+- **Parser**: Adjacent dot after keywords treated as property access, not CSS selector
+- **Behaviors**: Clipboard `wait feedbackDuration`, AutoDismiss wait timing, Removable confirm dialog
+- **Browser**: Resolver bundle timing and Playwright test stability
+- **CI**: Behaviors package added to build pipeline, artifact upload, and pre-publish-check build order
+
+## [2.2.1] - 2026-03-16
+
+### Fixed
+
+- Parser: adjacent dot after keywords treated as property access, not CSS selector
+- Dependency updates (build-tools group)
+
+## [2.2.0] - 2026-03-15
+
+### Fixed
+
+- Dependency security: resolved 27 of 33 Dependabot vulnerabilities
+- CI: copy examples gallery into repo, remove external clone dependency
+- CI: suppress already-published errors in publish dry run
+
+## [2.1.0] - 2026-02-20
+
+### Added
+
+- **domain-llm**: Expanded from 4 to 8 languages (added Korean, Chinese, Turkish, French) — 68 tests
+- **domain-flow**: Expanded from 4 to 8 languages (added Korean, Chinese, Turkish, French) — 108 tests
+- **domain-flow**: First npm publication as `@lokascript/domain-flow`
+
+### Changed
+
+- All 7 domain DSLs now consistently support 8 languages (en, es, ja, ar, ko, zh, tr, fr)
+- MCP server registry updated for new domain languages
+
+### Fixed
+
+- Resolved test failures in 4 packages (19 tests)
+- Scoped `first .X in me` to context element instead of document
+- Property target bugs: disabled on button, tabIndex as number
+
+## [2.0.0] - 2026-02-15
+
+### Changed
+
+- **Rebrand**: Renamed from LokaScript to HyperFixi for engine packages (`@lokascript/core` → `@hyperfixi/core`)
+- Multilingual packages remain under `@lokascript/*` scope
+- Synchronized all package versions to 2.0.0
+
+## [1.4.0] - 2026-02-10
+
+### Added
+
+- **Language Server & VSCode Extension**: Full LSP with Go to Definition, Find References, multilingual hover, syntax highlighting, and HTML region extraction
+- **AOT Compiler** (internal): Ahead-of-time compiler with 45 command codegens, expression transforms, 4 optimization passes, and 533 tests
+- **Compilation Service** (internal): HTTP service for multilingual compilation with React renderer, test generation, and semantic diffing
+- **Hyperscript Adapter** (@lokascript/hyperscript-adapter): Multilingual preprocessor plugin for original \_hyperscript with 24 per-language bundles
+- **Semantic**: Russian/Ukrainian normalizers, improved SOV pass rates (JA 99%, KO 96%, TR 96%)
+- **Vite Plugin**: htmx/fixi attribute scanning for zero-config support, hybrid-plus bundle commands
+
+### Changed
+
+- **Monorepo cleanup**: Moved experimental packages (analytics, server-integration, multi-tenant, ssr-support, siren) to `experiments/`
+- **Code audits**: Comprehensive audits across core (+58 tests), runtime (+34 tests), behaviors (+66 tests), expressions (9 security fixes), validation (+20 tests), features (+19 tests), i18n (+33 tests)
+- **Semantic refactoring**: Modularized tokenizer, split pattern generator by word order, eliminated all `as any` casts
+- **CI**: Consolidated workflows, switched to OIDC trusted publishing, upgraded to Node 24 LTS
+- **Test count**: 4046 → 8100+ tests
+
+### Fixed
+
+- Runtime correctness: GC fix, timeout handling, expression security hardening
+- Browser test timeouts and false CI failures
+- TypeScript errors across 6 packages for clean workspace typecheck
+- Debug console.log leak in set command
+
+## [1.3.0] - 2026-01-23
+
+_Synchronized version release. See git history for details._
+
+## [1.2.0] - 2026-01-21
+
+_Synchronized version release. See git history for details._
+
+## [1.0.0] - 2026-01-19
+
+### Added
+
+- **Initial Release**: First public release of LokaScript
+- **Core Package** (@lokascript/core): Full hyperscript runtime with 43 commands
+- **Semantic Package** (@lokascript/semantic): Multilingual parsing for 23 languages
+- **I18n Package** (@lokascript/i18n): Grammar transformation for SOV/VSO/SVO word orders
+- **Vite Plugin** (@lokascript/vite-plugin): Zero-config Vite integration
+- **MCP Server** (@lokascript/mcp-server): Model Context Protocol server for LLM integration
+- **Browser Bundles**: 7 size-optimized bundles (lite, lite-plus, hybrid-complete, hybrid-hx, minimal, standard, full)
+- **23 Language Support**: English, Spanish, Japanese, Korean, Arabic, Chinese, French, German, Portuguese, Indonesian, Turkish, Swahili, Quechua, and more
+- **4046 Tests**: Comprehensive test suite with >95% coverage
+- **Etymology**: "LokaScript" from Sanskrit "loka" (world/realm/universe) reflecting multilingual scope
+
+### Changed
+
+- **Rebrand**: Project renamed from HyperFixi to LokaScript
+- **NPM Organization**: Published under @lokascript/\* scope
+- **Browser API**: Primary global changed to window.lokascript (with window.hyperfixi backward compatibility)
+- **Lifecycle Events**: Renamed to lokascript:_ prefix (dual dispatch with hyperfixi:_ for compatibility)
+
+### Fixed
+
+- Workspace dependency resolution using wildcard versions (\*)
+- TypeScript compilation across all 20+ packages
+- Build system for browser bundles
+
+### Backward Compatibility
+
+- window.hyperfixi available as deprecated alias to window.lokascript
+- hyperfixi:_ events still dispatched alongside lokascript:_ events
+- File names kept for compatibility (e.g., hyperfixi-browser.js)
+
+### Documentation
+
+- Complete rebrand of all README files
+- Updated CLAUDE.md with project context
+- NPM organization setup guide
+- Version management documentation
+
+### Security
+
+- npm access token stored in GitHub Secrets
+- 2FA recommended for npm organization
+
+[Unreleased]: https://github.com/codetalcott/hyperfixi/compare/v2.4.0...HEAD
+[2.4.0]: https://github.com/codetalcott/hyperfixi/compare/v2.3.1...v2.4.0
+[2.3.1]: https://github.com/codetalcott/hyperfixi/compare/v2.3.0...v2.3.1
+[2.3.0]: https://github.com/codetalcott/hyperfixi/compare/v2.2.1...v2.3.0
+[2.2.1]: https://github.com/codetalcott/hyperfixi/compare/v2.2.0...v2.2.1
+[2.2.0]: https://github.com/codetalcott/hyperfixi/compare/v2.1.0...v2.2.0
+[2.1.0]: https://github.com/codetalcott/hyperfixi/compare/v2.0.0...v2.1.0
+[2.0.0]: https://github.com/codetalcott/hyperfixi/compare/v1.4.0...v2.0.0
+[1.4.0]: https://github.com/codetalcott/hyperfixi/compare/v1.3.0...v1.4.0
+[1.3.0]: https://github.com/codetalcott/hyperfixi/compare/v1.2.0...v1.3.0
+[1.2.0]: https://github.com/codetalcott/hyperfixi/compare/v1.0.0...v1.2.0
+[1.0.0]: https://github.com/codetalcott/hyperfixi/releases/tag/v1.0.0

package/README.md

@@ -21,16 +21,68 @@ HTML structure is preserved.
 
 ### Flags
 
-| Flag            | Description                                                                        |
-| --------------- | ---------------------------------------------------------------------------------- |
-| `--langs`, `-l` | Comma-separated target language codes (`ja,es,ko`).                                |
-| `--out`, `-o`   | Output directory. Defaults to `.`.                                                 |
-| `--from`, `-f`  | Source locale of the input. Defaults to `en`.                                      |
-| `--strict`      | Fail the run on any single attribute that can't be translated. Default is lenient. |
+| Flag            | Description                                                                                      |
+| --------------- | ------------------------------------------------------------------------------------------------ |
+| `--langs`, `-l` | Comma-separated target language codes (`ja,es,ko`).                                              |
+| `--out`, `-o`   | Output directory. Defaults to `.`.                                                               |
+| `--from`, `-f`  | Source locale of the input. Defaults to `en`.                                                    |
+| `--strict`      | Fail the run on any single attribute that can't be translated. Default is lenient.               |
+| `--check`       | Parse-check the English hyperscript on the real engine and exit 3 if any is invalid (see below). |
 
 Inputs may be individual files or directories — every `.html` in a directory
 is processed.
 
+## Canonical parse-check
+
+Every `_="..."` attribute this tool touches on the **English side** can be
+validated against the real [`hyperscript.org`](https://hyperscript.org) parser —
+the same engine the browser runs. This is checked for:
+
+- **input** when translating _from_ English (`--from en`, the default) — catches
+  an invalid canonical source before it ships in all 24 languages, and
+- **output** when a target language is `en` (foreign → English).
+
+Foreign-language _output_ is deliberately **not** round-trip-checked here: this
+package's grammar transformer is lossy in reverse, so a round-trip gate would be
+noise. Faithful foreign-output gating belongs to the semantic-engine transpiler
+(roadmap §5, "later").
+
+By default, invalid English prints a deduped warning and the run continues:
+
+```text
+sample.html: invalid hyperscript (English input -> ja): _="on click qqqq zzzz"
+  - Unexpected Token : qqqq
+```
+
+Pass `--check` to escalate to a build failure (exit code **3**) after all files
+are processed and written:
+
+```bash
+npx @hyperscript-tools/i18n translate src/page.html --langs ja,es --out dist/ --check
+```
+
+**Exit codes:** `0` success · `1` no inputs matched (or `--check` but the parser
+failed to load) · `2` usage error · `3` `--check` found invalid hyperscript.
+
+In the Eleventy plugin, use the `parseCheck` option (`'off' | 'warn' | 'error'`,
+default `'warn'`):
+
+```js
+eleventyConfig.addPlugin(hyperscriptI18n, { parseCheck: 'error' });
+```
+
+Programmatically:
+
+```ts
+import { validateHyperscript } from '@hyperscript-tools/i18n/validate';
+
+const errors = await validateHyperscript('on click toggle .active'); // [] = valid
+```
+
+> **Caveat:** the attribute scanner is a regex over `_="..."`, so hyperscript
+> inside HTML comments or `<script>` bodies is checked too. Warn-by-default keeps
+> that from breaking builds.
+
 ## Eleventy plugin
 
 ```js

package/dist/chunk-7ZOFDQYR.js

@@ -0,0 +1,57 @@
+// src/validate.ts
+import { createRequire } from "module";
+import { pathToFileURL } from "url";
+import path from "path";
+var cached;
+function loadValidator() {
+  if (!cached) {
+    cached = (async () => {
+      const require2 = createRequire(import.meta.url);
+      const iife = require2.resolve("hyperscript.org");
+      const esm = path.join(path.dirname(iife), "_hyperscript.esm.js");
+      const mod = await import(pathToFileURL(esm).href);
+      const hs = mod.default ?? mod;
+      if (typeof hs?.parse !== "function") {
+        throw new Error(
+          "Loaded hyperscript.org but it did not expose parse(); the package layout may have changed."
+        );
+      }
+      return (src) => {
+        try {
+          return (hs.parse(src)?.errors ?? []).map((e) => e.message.split("\n")[0]);
+        } catch (e) {
+          return ["threw: " + e.message.split("\n")[0]];
+        }
+      };
+    })();
+  }
+  return cached;
+}
+async function validateHyperscript(src) {
+  return (await loadValidator())(src);
+}
+function formatParseCheckReport(r) {
+  const code = r.code.length > 80 ? r.code.slice(0, 77) + "..." : r.code;
+  const where = r.stage === "input" ? `English input -> ${r.to}` : `English output <- ${r.from}`;
+  return [`invalid hyperscript (${where}): _="${code}"`, ...r.errors.map((e) => `  - ${e}`)].join(
+    "\n"
+  );
+}
+var warned = /* @__PURE__ */ new Set();
+function warnInvalidOnce(r) {
+  if (warned.has(r.code)) return false;
+  warned.add(r.code);
+  console.warn(`[hyperscript-i18n] ${formatParseCheckReport(r)}`);
+  return true;
+}
+function __resetParseCheckWarnings() {
+  warned.clear();
+}
+
+export {
+  loadValidator,
+  validateHyperscript,
+  formatParseCheckReport,
+  warnInvalidOnce,
+  __resetParseCheckWarnings
+};

package/dist/chunk-SYQOFAWY.js

@@ -0,0 +1,89 @@
+import {
+  formatParseCheckReport,
+  warnInvalidOnce
+} from "./chunk-7ZOFDQYR.js";
+
+// src/html.ts
+import { translate } from "@lokascript/i18n";
+var ATTR_PATTERNS = [
+  /(_\s*=\s*")([^"]+)(")/g,
+  /(_\s*=\s*')([^']+)(')/g,
+  /(_\s*=\s*`)([^`]+)(`)/g
+];
+function extractHyperscriptAttributes(html) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const pattern of ATTR_PATTERNS) {
+    for (const m of html.matchAll(pattern)) {
+      seen.add(m[2]);
+    }
+  }
+  return [...seen];
+}
+function checkHtmlInput(html, validate, to = "*") {
+  const reports = [];
+  for (const code of extractHyperscriptAttributes(html)) {
+    const errors = validate(code);
+    if (errors.length > 0) {
+      reports.push({ stage: "input", code, errors, from: "en", to });
+    }
+  }
+  return reports;
+}
+function dispatch(report, onInvalid) {
+  if (typeof onInvalid === "function") onInvalid(report);
+  else if (onInvalid === "error")
+    throw new Error(`[hyperscript-i18n] ${formatParseCheckReport(report)}`);
+  else warnInvalidOnce(report);
+}
+function translateHtml(html, to, options = {}) {
+  const from = options.from ?? "en";
+  const lenient = options.lenient ?? true;
+  const { validate } = options;
+  const onInvalid = options.onInvalid ?? "warn";
+  if (from === to) return html;
+  if (validate && options.checkInput !== false && from === "en") {
+    for (const report of checkHtmlInput(html, validate, to)) dispatch(report, onInvalid);
+  }
+  let out = html;
+  for (const pattern of ATTR_PATTERNS) {
+    out = out.replace(pattern, (_match, before, body, after) => {
+      let translated;
+      try {
+        translated = translate(body, from, to);
+      } catch (err) {
+        if (lenient) return `${before}${body}${after}`;
+        throw err;
+      }
+      if (validate && to === "en") {
+        const errors = validate(translated);
+        if (errors.length > 0) {
+          dispatch({ stage: "output", code: translated, errors, from, to }, onInvalid);
+        }
+      }
+      return `${before}${translated}${after}`;
+    });
+  }
+  return out;
+}
+function translateHtmlToManyLangs(html, langs, options = {}) {
+  const from = options.from ?? "en";
+  let perLang = options;
+  if (options.validate && options.checkInput !== false && from === "en") {
+    for (const report of checkHtmlInput(html, options.validate)) {
+      dispatch(report, options.onInvalid ?? "warn");
+    }
+    perLang = { ...options, checkInput: false };
+  }
+  const out = /* @__PURE__ */ new Map();
+  for (const lang of langs) {
+    out.set(lang, translateHtml(html, lang, perLang));
+  }
+  return out;
+}
+
+export {
+  extractHyperscriptAttributes,
+  checkHtmlInput,
+  translateHtml,
+  translateHtmlToManyLangs
+};

package/dist/cli.js

@@ -1,7 +1,12 @@
 #!/usr/bin/env node
 import {
+  checkHtmlInput,
   translateHtml
-} from "./chunk-XIEA5H7Z.js";
+} from "./chunk-SYQOFAWY.js";
+import {
+  formatParseCheckReport,
+  loadValidator
+} from "./chunk-7ZOFDQYR.js";
 
 // src/cli.ts
 import { mkdirSync, readFileSync, writeFileSync, existsSync, statSync, readdirSync } from "fs";
@@ -13,7 +18,8 @@ function parseArgs(argv) {
     langs: [],
     from: "en",
     out: ".",
-    strict: false
+    strict: false,
+    check: false
   };
   if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") return args;
   args.command = argv[0] === "translate" ? "translate" : "help";
@@ -28,6 +34,8 @@ function parseArgs(argv) {
       args.from = argv[++i] ?? "en";
     } else if (a === "--strict") {
       args.strict = true;
+    } else if (a === "--check") {
+      args.check = true;
     } else if (a.startsWith("-")) {
       throw new Error(`Unknown flag: ${a}`);
     } else {
@@ -59,7 +67,7 @@ function printHelp() {
   console.log(`hyperscript-i18n \u2014 translate _="..." attributes in HTML
 
 Usage:
-  hyperscript-i18n translate <input> [<input> ...] --langs <codes> --out <dir> [--from <code>] [--strict]
+  hyperscript-i18n translate <input> [<input> ...] --langs <codes> --out <dir> [--from <code>] [--strict] [--check]
 
 Options:
   --langs, -l   Comma-separated target language codes (e.g. ja,es,ko).
@@ -67,10 +75,20 @@ Options:
   --from, -f    Source locale of the input. Defaults to 'en'.
   --strict      Fail the run if any single attribute fails to translate.
                 Default is lenient: untranslatable snippets are left in place.
+  --check       Validate the ENGLISH hyperscript on the real hyperscript.org
+                parser (input when --from en; output when a target is en) and
+                exit 3 if any attribute is invalid. Without --check, invalid
+                attributes only print a warning.
 
 Output:
   For each input file foo.html and each lang, writes <out>/foo.<lang>.html.
 
+Exit codes:
+  0  success
+  1  no HTML inputs matched, or --check requested but the parser failed to load
+  2  usage error (bad flags / missing --langs / no inputs)
+  3  --check found invalid hyperscript
+
 Example:
   hyperscript-i18n translate src/patterns.html --langs ja,es,ko --out dist/
 `);
@@ -101,14 +119,43 @@ async function run(argv) {
     return 1;
   }
   mkdirSync(args.out, { recursive: true });
+  let validate;
+  try {
+    validate = await loadValidator();
+  } catch (err) {
+    const msg = err.message;
+    if (args.check) {
+      console.error(`--check requested but the canonical parser failed to load: ${msg}`);
+      return 1;
+    }
+    console.warn(`parse-check disabled (could not load hyperscript.org): ${msg}`);
+  }
+  const failures = [];
+  const printedCodes = /* @__PURE__ */ new Set();
+  const recorderFor = (file) => (report) => {
+    failures.push({ file, ...report });
+    if (!printedCodes.has(report.code)) {
+      printedCodes.add(report.code);
+      console.warn(`${file}: ${formatParseCheckReport(report)}`);
+    }
+  };
   let written = 0;
   for (const file of files) {
     const html = readFileSync(file, "utf8");
     const stem = basename(file, extname(file));
+    const onInvalid = recorderFor(file);
+    if (validate && args.from === "en") {
+      for (const report of checkHtmlInput(html, validate)) onInvalid(report);
+    }
     for (const lang of args.langs) {
       const translated = translateHtml(html, lang, {
         from: args.from,
-        lenient: !args.strict
+        lenient: !args.strict,
+        validate,
+        // still drives the OUTPUT check when lang === 'en'
+        checkInput: false,
+        // input already checked once above
+        onInvalid
       });
       const outPath = join(args.out, `${stem}.${lang}.html`);
       mkdirSync(dirname(outPath), { recursive: true });
@@ -119,6 +166,19 @@ async function run(argv) {
   console.log(
     `Wrote ${written} files (${files.length} input \xD7 ${args.langs.length} langs) to ${args.out}`
   );
+  if (args.check && failures.length > 0) {
+    const fileCount = new Set(failures.map((f) => f.file)).size;
+    console.error(
+      `
+Parse-check failed: ${failures.length} invalid hyperscript attribute(s) in ${fileCount} file(s):`
+    );
+    for (const f of failures) {
+      console.error(
+        `  ${f.file} [${f.stage}]: ${formatParseCheckReport(f).split("\n").join("\n  ")}`
+      );
+    }
+    return 3;
+  }
   return 0;
 }
 var isMain = import.meta.url === `file://${process.argv[1]}`;

package/dist/eleventy.d.ts

@@ -1,6 +1,7 @@
 import { LangCode } from './index.js';
 export { TranslateHtmlOptions, translateHtml, translateHtmlToManyLangs } from './index.js';
 import '@lokascript/i18n';
+import './validate.js';
 
 /**
  * Eleventy plugin entry: `@hyperscript-tools/i18n/eleventy`
@@ -22,6 +23,13 @@ import '@lokascript/i18n';
  *   export default function (eleventyConfig) {
  *     eleventyConfig.addPlugin(hyperscriptI18n);
  *   }
+ *
+ * The plugin is ASYNC: when `parseCheck` is on (the default), it awaits the
+ * canonical `hyperscript.org` parser before returning. Eleventy 3 awaits plugin
+ * callbacks passed to `addPlugin`, so the check is active before any template
+ * renders. All three filters are registered SYNCHRONOUSLY before that await, so
+ * an un-awaited caller (or Eleventy 2) still gets working filters — the check
+ * simply activates once the parser finishes loading.
  */
 
 interface EleventyPluginOptions {
@@ -29,6 +37,14 @@ interface EleventyPluginOptions {
     defaultFrom?: LangCode;
     /** Default lenient flag for HTML translation. Defaults to true. */
     lenient?: boolean;
+    /**
+     * Canonical parse-check for the ENGLISH side (input when source is 'en';
+     * output when a target is 'en'):
+     *   'off'   — no check
+     *   'warn'  — print a deduped warning for invalid English (default)
+     *   'error' — throw, failing the build
+     */
+    parseCheck?: 'off' | 'warn' | 'error';
     /** Override filter names (in case of collisions in your config). */
     filterNames?: {
         snippet?: string;
@@ -39,6 +55,6 @@ interface EleventyPluginOptions {
 interface EleventyConfig {
     addFilter(name: string, fn: (...args: unknown[]) => unknown): void;
 }
-declare function hyperscriptI18nPlugin(eleventyConfig: EleventyConfig, options?: EleventyPluginOptions): void;
+declare function hyperscriptI18nPlugin(eleventyConfig: EleventyConfig, options?: EleventyPluginOptions): Promise<void>;
 
 export { type EleventyPluginOptions, LangCode, hyperscriptI18nPlugin as default };

package/dist/eleventy.js

@@ -1,31 +1,52 @@
 import {
   translateHtml,
   translateHtmlToManyLangs
-} from "./chunk-XIEA5H7Z.js";
+} from "./chunk-SYQOFAWY.js";
+import {
+  formatParseCheckReport,
+  loadValidator,
+  warnInvalidOnce
+} from "./chunk-7ZOFDQYR.js";
 
 // src/eleventy.ts
 import { translate } from "@lokascript/i18n";
-function hyperscriptI18nPlugin(eleventyConfig, options = {}) {
+async function hyperscriptI18nPlugin(eleventyConfig, options = {}) {
   const defaultFrom = options.defaultFrom ?? "en";
   const lenient = options.lenient ?? true;
+  const parseCheck = options.parseCheck ?? "warn";
   const names = {
     snippet: options.filterNames?.snippet ?? "translateHs",
     snippetMany: options.filterNames?.snippetMany ?? "translateHsAll",
     html: options.filterNames?.html ?? "translateHsHtml"
   };
+  let validate;
+  const check = (code, stage, from, to) => {
+    if (!validate) return;
+    const errors = validate(code);
+    if (errors.length === 0) return;
+    const report = { stage, code, errors, from, to };
+    if (parseCheck === "error")
+      throw new Error(`[hyperscript-i18n] ${formatParseCheckReport(report)}`);
+    warnInvalidOnce(report);
+  };
   eleventyConfig.addFilter(names.snippet, (input, to, from) => {
     if (typeof input !== "string" || typeof to !== "string") return input;
     const source = typeof from === "string" ? from : defaultFrom;
     if (source === to) return input;
+    if (source === "en") check(input, "input", source, to);
+    let out;
     try {
-      return translate(input, source, to);
+      out = translate(input, source, to);
     } catch {
       return lenient ? input : "";
     }
+    if (to === "en") check(out, "output", source, to);
+    return out;
   });
   eleventyConfig.addFilter(names.snippetMany, (input, langs, from) => {
     if (typeof input !== "string" || !Array.isArray(langs)) return {};
     const source = typeof from === "string" ? from : defaultFrom;
+    if (source === "en") check(input, "input", source, "*");
     const out = {};
     for (const lang of langs) {
       if (typeof lang !== "string") continue;
@@ -37,7 +58,9 @@ function hyperscriptI18nPlugin(eleventyConfig, options = {}) {
         out[lang] = translate(input, source, lang);
       } catch {
         out[lang] = lenient ? input : "";
+        continue;
       }
+      if (lang === "en") check(out[lang], "output", source, "en");
     }
     return out;
   });
@@ -45,10 +68,28 @@ function hyperscriptI18nPlugin(eleventyConfig, options = {}) {
     if (typeof html !== "string" || typeof to !== "string") return html;
     const opts = {
       from: typeof from === "string" ? from : defaultFrom,
-      lenient
+      lenient,
+      validate: parseCheck === "off" ? void 0 : validate,
+      checkInput: true,
+      onInvalid: parseCheck === "error" ? "error" : "warn"
     };
     return translateHtml(html, to, opts);
   });
+  if (parseCheck !== "off") {
+    try {
+      validate = await loadValidator();
+    } catch (err) {
+      const msg = err.message;
+      if (parseCheck === "error") {
+        throw new Error(
+          `[hyperscript-i18n] parseCheck 'error' but the canonical parser failed to load: ${msg}`
+        );
+      }
+      console.warn(
+        `[hyperscript-i18n] parse-check disabled (could not load hyperscript.org): ${msg}`
+      );
+    }
+  }
 }
 export {
   hyperscriptI18nPlugin as default,

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { GrammarTransformer, toEnglish, toLocale, translate } from '@lokascript/i18n';
+import { CanonicalValidate, ParseCheckReport } from './validate.js';
+export { formatParseCheckReport, loadValidator, validateHyperscript } from './validate.js';
 
 /**
  * HTML attribute scanner + translator.
@@ -7,8 +9,16 @@ export { GrammarTransformer, toEnglish, toLocale, translate } from '@lokascript/
  * attributes, translates each from a source locale to a target locale, and
  * returns the rewritten HTML. The grammar transformer doesn't know about HTML;
  * this module is the glue.
+ *
+ * Optionally parse-checks the ENGLISH side against the real `hyperscript.org`
+ * engine (see ./validate): the input when `from === 'en'` and the output when
+ * `to === 'en'`. The check only runs when a `validate` function is supplied, so
+ * existing callers see no behaviour change.
  */
+
 type LangCode = string;
+/** What to do with an invalid-English report. */
+type OnInvalid = 'warn' | 'error' | ((report: ParseCheckReport) => void);
 interface TranslateHtmlOptions {
     /** Source locale of the input HTML's `_=` attributes. Defaults to 'en'. */
     from?: LangCode;
@@ -18,8 +28,30 @@ interface TranslateHtmlOptions {
      * whole page build.
      */
     lenient?: boolean;
+    /**
+     * Canonical validator (from `loadValidator()`). When absent, no parse-check
+     * runs and behaviour is unchanged.
+     */
+    validate?: CanonicalValidate;
+    /** What to do with an invalid-English report. Default 'warn' (deduped console.warn). */
+    onInvalid?: OnInvalid;
+    /**
+     * Set false when the caller already validated the English input (as
+     * `translateHtmlToManyLangs` and the CLI do). Default true.
+     */
+    checkInput?: boolean;
 }
+/**
+ * Every `_=` attribute body in `html` (double/single/backtick quoted), deduped,
+ * in document order.
+ */
+declare function extractHyperscriptAttributes(html: string): string[];
+/**
+ * Validate every English `_=` attribute body of `html`; returns a report for
+ * each invalid one (stage 'input').
+ */
+declare function checkHtmlInput(html: string, validate: CanonicalValidate, to?: LangCode): ParseCheckReport[];
 declare function translateHtml(html: string, to: LangCode, options?: TranslateHtmlOptions): string;
 declare function translateHtmlToManyLangs(html: string, langs: ReadonlyArray<LangCode>, options?: TranslateHtmlOptions): Map<LangCode, string>;
 
-export { type LangCode, type TranslateHtmlOptions, translateHtml, translateHtmlToManyLangs };
+export { CanonicalValidate, type LangCode, type OnInvalid, ParseCheckReport, type TranslateHtmlOptions, checkHtmlInput, extractHyperscriptAttributes, translateHtml, translateHtmlToManyLangs };

package/dist/index.js

@@ -1,15 +1,27 @@
 import {
+  checkHtmlInput,
+  extractHyperscriptAttributes,
   translateHtml,
   translateHtmlToManyLangs
-} from "./chunk-XIEA5H7Z.js";
+} from "./chunk-SYQOFAWY.js";
+import {
+  formatParseCheckReport,
+  loadValidator,
+  validateHyperscript
+} from "./chunk-7ZOFDQYR.js";
 
 // src/index.ts
 import { translate, toLocale, toEnglish, GrammarTransformer } from "@lokascript/i18n";
 export {
   GrammarTransformer,
+  checkHtmlInput,
+  extractHyperscriptAttributes,
+  formatParseCheckReport,
+  loadValidator,
   toEnglish,
   toLocale,
   translate,
   translateHtml,
-  translateHtmlToManyLangs
+  translateHtmlToManyLangs,
+  validateHyperscript
 };

package/dist/validate.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Canonical parse-check.
+ *
+ * Loads the REAL `hyperscript.org` engine headlessly (parse-only needs no DOM)
+ * and exposes a validate function that NEVER throws. The engine has two failure
+ * channels: `parse().errors` COLLECTS grammar errors, but the tokenizer THROWS
+ * on an unknown character (e.g. a leaked non-ASCII surface → `Unknown token: เ`)
+ * and the `js` command's `new Function` throws on invalid JavaScript. Both
+ * throws are folded into the returned array so callers have one contract —
+ * check `.length === 0`, never wrap in try/catch expecting invalidity to throw.
+ *
+ * Self-contained on purpose: node builtins + `hyperscript.org` only, no
+ * `@lokascript/*` or `@hyperfixi/*` imports, so the package stays extraction-ready.
+ */
+/** Parse `src` on the canonical engine; returns error messages (empty = valid). Never throws. */
+type CanonicalValidate = (src: string) => string[];
+interface ParseCheckReport {
+    /** 'input' = English source before translating; 'output' = English produced from a foreign source. */
+    stage: 'input' | 'output';
+    /** The invalid English hyperscript. */
+    code: string;
+    /** Canonical parser error messages (first line each). */
+    errors: string[];
+    /** Source locale of the translate call ('en' for stage 'input'). */
+    from: string;
+    /** Target locale ('en' for stage 'output'; '*' for an aggregated input check). */
+    to: string;
+}
+/**
+ * Load (once, module-cached) the canonical validator. Resolve `hyperscript.org`,
+ * then import the sibling prebuilt `_hyperscript.esm.js` by file URL. Rejects if
+ * the package cannot be loaded or does not expose `parse()`.
+ */
+declare function loadValidator(): Promise<CanonicalValidate>;
+/** Convenience: load (cached) and validate in one call. */
+declare function validateHyperscript(src: string): Promise<string[]>;
+/** Multi-line human-readable rendering of a report (head line + one `  - <error>` line each). */
+declare function formatParseCheckReport(r: ParseCheckReport): string;
+/** Default warn printer; dedupes by `r.code` per process. Returns true if it printed. */
+declare function warnInvalidOnce(r: ParseCheckReport): boolean;
+/** @internal test hook — clears the per-process warn-dedupe set. */
+declare function __resetParseCheckWarnings(): void;
+
+export { type CanonicalValidate, type ParseCheckReport, __resetParseCheckWarnings, formatParseCheckReport, loadValidator, validateHyperscript, warnInvalidOnce };

package/dist/validate.js

@@ -0,0 +1,14 @@
+import {
+  __resetParseCheckWarnings,
+  formatParseCheckReport,
+  loadValidator,
+  validateHyperscript,
+  warnInvalidOnce
+} from "./chunk-7ZOFDQYR.js";
+export {
+  __resetParseCheckWarnings,
+  formatParseCheckReport,
+  loadValidator,
+  validateHyperscript,
+  warnInvalidOnce
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperscript-tools/i18n",
-  "version": "2.7.2",
+  "version": "2.9.0",
   "description": "Build-time translation for hyperscript code samples — generate per-language HTML from a canonical English source",
   "type": "module",
   "main": "dist/index.js",
@@ -19,15 +19,19 @@
     },
     "./cli": {
       "default": "./dist/cli.js"
+    },
+    "./validate": {
+      "types": "./dist/validate.d.ts",
+      "import": "./dist/validate.js"
     }
   },
   "scripts": {
-    "build": "tsup src/index.ts src/cli.ts src/eleventy.ts --format esm --dts --clean",
-    "dev": "tsup src/index.ts src/cli.ts src/eleventy.ts --format esm --dts --watch",
+    "build": "tsup src/index.ts src/cli.ts src/eleventy.ts src/validate.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts src/cli.ts src/eleventy.ts src/validate.ts --format esm --dts --watch",
     "typecheck": "tsc --noEmit",
     "pretest": "../../scripts/ensure-fresh.sh ../i18n . && npm run build --silent",
     "test": "node --test test/*.test.mjs",
-    "test:check": "node --test --test-reporter=spec test/*.test.mjs 2>&1 | tail -10"
+    "test:check": "bash -c 'set -o pipefail; node --test --test-reporter=spec test/*.test.mjs 2>&1 | tail -10'"
   },
   "keywords": [
     "hyperscript",
@@ -44,7 +48,8 @@
   "author": "HyperFixi Contributors",
   "license": "MIT",
   "dependencies": {
-    "@lokascript/i18n": "^2.7.2"
+    "@lokascript/i18n": "^2.9.0",
+    "hyperscript.org": "^0.9.93"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -54,7 +59,8 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "publishConfig": {
     "access": "public"

package/dist/chunk-XIEA5H7Z.js

@@ -1,37 +0,0 @@
-// src/html.ts
-import { translate } from "@lokascript/i18n";
-var ATTR_PATTERNS = [
-  /(_\s*=\s*")([^"]+)(")/g,
-  /(_\s*=\s*')([^']+)(')/g,
-  /(_\s*=\s*`)([^`]+)(`)/g
-];
-function translateHtml(html, to, options = {}) {
-  const from = options.from ?? "en";
-  const lenient = options.lenient ?? true;
-  if (from === to) return html;
-  let out = html;
-  for (const pattern of ATTR_PATTERNS) {
-    out = out.replace(pattern, (_match, before, body, after) => {
-      try {
-        const translated = translate(body, from, to);
-        return `${before}${translated}${after}`;
-      } catch (err) {
-        if (lenient) return `${before}${body}${after}`;
-        throw err;
-      }
-    });
-  }
-  return out;
-}
-function translateHtmlToManyLangs(html, langs, options = {}) {
-  const out = /* @__PURE__ */ new Map();
-  for (const lang of langs) {
-    out.set(lang, translateHtml(html, lang, options));
-  }
-  return out;
-}
-
-export {
-  translateHtml,
-  translateHtmlToManyLangs
-};