@hyperfixi/vite-plugin 3.3.0 → 4.0.1

package/README.md

@@ -1,19 +1,21 @@
 # @hyperfixi/vite-plugin
 
-Zero-config Vite plugin that automatically generates minimal LokaScript bundles based on detected hyperscript usage.
+Zero-config Vite plugin that emits a bundle on [`@hyperfixi/engine`](../engine/README.md) registering only the grammar modules your hyperscript uses.
 
 ## Features
 
 - **Zero-config**: Just add the plugin and it works
 - **Automatic detection**: Scans HTML, Vue, Svelte, JSX/TSX for `_="..."` attributes
-- **Minimal bundles**: Only includes commands and blocks you actually use
+- **Minimal bundles**: Registers only the engine modules your commands and blocks need (17.9 KB gzipped for three commands, 34.4 KB for everything)
+- **Upstream's grammar**: The engine is gated by `_hyperscript`'s own test suite, so what works on `hyperfixi-hs.js` works in the generated bundle
+- **Multilingual**: Non-English scripts are translated as the engine reads them (the attribute stays as written)
 - **HMR support**: Re-generates bundle when you add new hyperscript
 - **Framework agnostic**: Works with any Vite-based project
 
 ## Installation
 
 ```bash
-npm install @hyperfixi/vite-plugin @hyperfixi/core
+npm install @hyperfixi/vite-plugin @hyperfixi/engine
 ```
 
 ## Quick Start
@@ -29,7 +31,7 @@ export default {
 
 ```javascript
 // main.js
-import 'hyperfixi'; // Auto-generated minimal bundle
+import 'hyperfixi'; // the generated bundle: the engine + your modules
 ```
 
 ```html
@@ -40,47 +42,44 @@ import 'hyperfixi'; // Auto-generated minimal bundle
 ## How It Works
 
 1. **Scans** your HTML/Vue/Svelte/JSX files for `_="..."` attributes
-2. **Detects** which commands, blocks, and expressions you use
-3. **Generates** a minimal bundle with only the features you need
+2. **Detects** which commands, blocks, and expression kinds you use
+3. **Emits** a bundle on [`@hyperfixi/engine`](../engine/README.md) that registers only
+   the grammar modules those need — a bundle on the engine is the list passed to
+   `register()`, so there is one tier: the modules. The emitted module is a few
+   lines; Vite bundles the engine's modules into it.
 4. **Regenerates** on HMR when you add new hyperscript
 
-## Compile Mode (Minimal Bundle Size)
-
-When bundle size is the priority, use **compile mode** to pre-compile hyperscript to JavaScript at build time:
-
 ```javascript
-hyperfixi({
-  mode: 'compile', // ~500 bytes gzip vs ~8KB for interpret mode
-});
+// What the virtual module looks like for a page using toggle, add and an if block
+import {
+  api,
+  boot,
+  register,
+  on,
+  conversions,
+  add,
+  toggle,
+  ifCommand,
+  toggleElement,
+} from '@hyperfixi/engine';
+register(on, conversions, add, toggle, ifCommand, toggleElement);
+window.hyperfixi = api; // the same object boot() installs as window._hyperscript
+boot();
+export default api;
 ```
 
-**Trade-offs:**
-
-| Feature             | Interpret (default) | Compile         |
-| ------------------- | ------------------- | --------------- |
-| Bundle size         | ~8 KB gzip          | ~500 bytes gzip |
-| Dynamic `execute()` | ✓                   | ✗               |
-| Block commands      | ✓                   | ✗               |
-| Build complexity    | Lower               | Higher          |
-
-**When to use compile mode:**
-
-- Landing pages with simple interactions (toggles, shows, hides)
-- Performance-critical apps where every KB matters
-- Static sites where hyperscript is just for UI polish
+The engine's parser is upstream `_hyperscript`'s grammar (its vendored test suite
+is the gate), so a generated bundle reads exactly what `hyperfixi-hs.js` reads;
+only the command set differs. Scanning is by word, so a name the engine has no
+module for (a false positive in a string, or a form the engine dropped) selects
+nothing; `debug: true` lists them.
 
-**When NOT to use compile mode:**
+## Compile Mode (removed in 4.0)
 
-- Apps using `if`, `repeat`, `fetch`, or `for each` blocks
-- Dynamic hyperscript generation at runtime via `execute()`
-- Apps that need the full hyperscript power
-
-**Supported commands in compile mode:**
-toggle, add, remove, show, hide, focus, blur, set, get, put, increment, decrement, log, send, trigger, wait
-
-**Positional expressions:** next, previous, parent, first, last, closest
-
-**Animations:** Use CSS transitions - toggling classes triggers them automatically. No special `transition` command needed.
+`mode: 'compile'` pre-compiled handlers to JavaScript with `@hyperfixi/core`'s hybrid
+parser (~500 bytes for a page of toggles). It was parked with the AOT compiler (owner
+decision 2026-10-03) and left with core's parser in 4.0. Selecting it logs a warning and
+builds the engine-module bundle above, which is the product.
 
 ## Multilingual & Semantic Parsing
 
@@ -158,40 +157,44 @@ per language, so the final size depends on Vite's tree-shaking; for reference, t
 prebuilt standalone semantic bundles range from ~90 KB (no languages) to ~260 KB
 (all 24 languages) gzipped, measured locally — see `docs/BROWSER_BUNDLES.md` in the repo.
 
-### Tiered Bundle Architecture
-
-```text
-Level 0: Base HybridParser (default)
-         ↓ semantic: true
-Level 1: + Semantic English
-         ↓ languages detected/specified
-Level 2: + Regional Semantic Bundle
-         ↓ grammar: true
-Level 3: + translateHyperscript() (semantic's translate)
-```
-
-Each level adds bundle weight; the plugin picks the lowest level that covers the
-features and languages it detects in your source.
-
-## htmx v4 reactive / streaming surface
+### How the multilingual bundle works
 
-The scanner detects `hx-live`, `sse-connect` / `sse-swap`, `ws-connect` / `ws-send`, and `bind <var> to <expr>.<prop>` inside `_=` bodies. When any of those is found in the project, the generated bundle is the `hyperfixi-hx-v4.js` premade bundle (full runtime + `@hyperfixi/reactivity` + htmx-compat auto-installed + SSE/WS).
-
-```html
-<!-- Triggers the hx-v4 fallback automatically -->
-<div hx-live="put $count into me"></div>
-<div sse-connect="/stream" sse-swap="tick" hx-target="#out"></div>
-<form ws-send><input name="msg" /></form>
-<input _="on input bind $val to me.value" />
-```
-
-The slim minimal-bundle generator can't satisfy these features (its parser/runtime doesn't know `live`/`when`/`bind`, doesn't route writes through `notifyGlobalWrite`, and doesn't ship the SSE/WS modules), so the plugin opts into the full hx-v4 bundle for correctness over size. If size matters more, drop the v4 attributes and use plain `_=` / v1-v2 htmx attributes.
+Text is the interchange. When semantic parsing is enabled the emitted bundle imports
+`@lokascript/semantic/core` plus one `@lokascript/semantic/languages/<code>` module
+per language and installs a **source transform** on the engine
+(`api.addSourceTransform`): a non-English script is parsed in its language and
+rendered to English as the engine reads it, and the element's attribute stays as
+written. The language comes from `data-lang`, `data-hyperscript-lang`, the nearest
+`lang` ancestor, or the document's `lang`. English scripts pass through untouched.
+
+The API gains `translateSource(src, element)` (what the transform does, for one
+script) and, with `grammar: true`, `translateHyperscript(code, from, to)`.
+
+Measured 2026-10-03, gzipped: three commands + Spanish is ~209 KB, of which the
+engine is 18 KB — the rest is semantic's parser and the language. Keep the language
+list to what the page uses.
+
+## Reactivity, htmx, and streaming
+
+`live … end`, `when … changes`, `bind` and `^var` inside `_=` bodies are the
+engine's reactive features: the scanner detects them and the bundle registers the
+engine's `reactivity` and `liveTemplates` modules (+2 KB gzipped). No separate
+bundle, no separate package.
+
+htmx is not bundled. Load htmx 4 beside the generated bundle for `hx-get` and
+friends, `hx-sse` / `hx-ws` for streams, and
+[`@lokascript/htmx-adapter`](../htmx-adapter/README.md) for localized attribute
+names (the two stacks in [docs/BROWSER_BUNDLES.md](../../docs/BROWSER_BUNDLES.md)).
+When the scan finds htmx attributes (or `htmx: true` is set) the bundle hands
+swapped-in content to the engine on `htmx:load` / `htmx:afterSettle`. A
+hyperscript-bodied `hx-live` attribute is a `_="live … end"` block on the engine;
+`sse-connect` / `ws-connect` are htmx 4's `hx-sse` / `hx-ws`.
 
 ## Options
 
 ```javascript
 hyperfixi({
-  // Bundle mode: 'interpret' (default) or 'compile'
+  // Bundle mode: 'interpret' (default; 'compile' was removed in 4.0, see above)
   mode: 'interpret',
 
   // Extra commands to always include (for dynamic hyperscript)
@@ -201,9 +204,12 @@ hyperfixi({
   // Always include positional expressions
   positional: true,
 
-  // Enable htmx attribute compatibility
+  // Hand htmx-swapped content to the engine (on by default when hx-* attributes are found)
   htmx: true,
 
+  // Dev-server bundle: 'everything' (the whole engine, faster rebuilds) or 'auto' (the module list)
+  devFallback: 'auto',
+
   // Debug logging
   debug: true,
 
@@ -228,18 +234,13 @@ hyperfixi({
 
 ## Detected Features
 
-### Commands
-
-toggle, add, remove, removeClass, show, hide, set, get, put, append, take,
-increment, decrement, log, send, trigger, wait, transition, go, call, focus, blur, return
-
-### Blocks (5)
-
-if, repeat, for, while, fetch
-
-### Positional Expressions (6)
-
-first, last, next, previous, closest, parent
+The scanner's word list is **derived from the engine** at load: every command and
+feature keyword its modules register (`add`, `call`, `for`, `tell`, `make`, …).
+Blocks: `if`, `repeat`, `for`, `while`, `fetch`. Expression kinds that select the
+engine's optional `expressionsExtra` module: `first`, `last`, `next`, `previous`,
+`closest`, `parent`, `random`, `where`, `sorted by`, `mapped to`, `split by`,
+`joined by`, `some`, `beep!`. Also `new X(…)` (the engine's `construct`
+addition) and `cookies`. `on` and the `as` conversions are always registered.
 
 ## Virtual Module
 
@@ -262,12 +263,22 @@ When you add new hyperscript to your HTML files, the plugin:
 
 ## Bundle Size Comparison
 
-| Usage               | Generated Size (gzip) | vs Full Bundle |
-| ------------------- | --------------------- | -------------- |
-| 3 commands          | ~5 KB                 | 90% smaller    |
-| 6 commands          | ~6.5 KB               | 85% smaller    |
-| 9 commands + blocks | ~8 KB                 | 80% smaller    |
-| All features        | ~40 KB                | same           |
+Measured 2026-10-03 (esbuild, minified, gzipped; `@hyperfixi/engine` 3.3.0):
+
+| Usage                                                | Generated size (gzip) |
+| ---------------------------------------------------- | --------------------- |
+| 3 commands (toggle, add, remove)                     | 17.9 KB               |
+| 7 commands (+ show, hide, put, set)                  | 18.7 KB               |
+| 5 commands + `if` / `repeat`                         | 19.6 KB               |
+| 10 commands + `if` / `repeat` / `fetch` + positional | 22.8 KB               |
+| + reactivity (`live` / `when` / `bind`)              | 20.3 KB               |
+| everything (the dev fallback; = `hyperfixi-hs.js`)   | 34.4 KB               |
+
+The engine's fixed cost (tokenizer, parser, the core expression kinds, runtime) is
+13.8 KB, so there is no sub-5 KB tier any more: the 3.x generator's regex "lite"
+parser emitted 3.9 KB for three commands, its hybrid parser 12–16 KB, and any page
+using `fetch` or one of twenty other commands fell back to the 352 KB `hyperfixi.js`.
+What you get in exchange is one grammar, gated by upstream's own test suite.
 
 ## Edge Cases
 
@@ -297,23 +308,17 @@ hyperfixi({
 
 ## Monorepo Development
 
-When developing in the hyperfixi monorepo:
+When developing in the hyperfixi monorepo, point the plugin at its source; the
+emitted bundle's `@hyperfixi/engine` import resolves through the workspace
+(build the engine first: `npm run build --prefix packages/engine`):
 
 ```javascript
 // vite.config.js
 import { hyperfixi } from '../../packages/vite-plugin/src/index.ts';
-import path from 'path';
 
 export default {
   plugins: [hyperfixi({ debug: true })],
-  resolve: {
-    alias: {
-      '@hyperfixi/core/parser/hybrid': path.resolve(
-        __dirname,
-        '../../packages/core/src/parser/hybrid'
-      ),
-    },
-  },
+  optimizeDeps: { exclude: ['hyperfixi', 'virtual:hyperfixi'] },
 };
 ```