@hyperfixi/types-browser 3.3.0 → 4.0.0

package/CHANGELOG.md

@@ -7,6 +7,168 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.0.0] - 2026-10-04
+
+`@hyperfixi/core`'s own hyperscript engine is gone: its root re-exports `@hyperfixi/engine`, and
+its `hyperfixi.js` is the engine's 34 KB script-tag bundle where core's ~352 KB bundle used to be.
+The engine follows upstream `_hyperscript`'s grammar and is gated by upstream's own test suite, so
+scripts in core-only syntax need upstream's spelling (two additions stay: `new X()` and
+`toggle <element>`). Core's other bundles, its htmx layer, the core-era plugin packages and the
+AOT compiler retire: htmx 4 or fixi supply hypermedia attributes beside the engine, and
+`@lokascript/hyperscript-adapter` runs hyperscript written in other languages. Every package moves
+to 4.0.0 together. Everything under **Removed** is breaking, as is each **Changed** item marked ⚠;
+[MIGRATION.md](MIGRATION.md) names each replacement.
+
+### Removed
+
+- **Core's engine and its API** (#1368). These root exports had no engine counterpart:
+  `hyperscript` (`compile`, `compileSync`, `compileAsync`, `eval`, `validate`), `lokascript`,
+  `Runtime`, `RuntimeBase`, `createContext` and the element-scope helpers, `installPlugin`,
+  `getParserExtensionRegistry`, `setGlobal`, `DebugController`, `validatePartialContent` and its
+  helpers, `fromCoreAST` / `toCoreAST`. `parse` is now the engine's. The root is ESM-only, like the
+  engine: `dist/index.cjs` and the UMD `dist/index.min.js` (`LokaScriptCore`) are gone, though the
+  kept subpaths still ship CommonJS.
+- **21 of core's 29 entry points**: `/commands`, `/expressions`, `/parser/*`, `/behaviors`,
+  `/bundle-generator`, `/registry/*`, `/lse`, and `/browser/` `hybrid-complete`, `hybrid-hx`,
+  `hybrid-hx-v4`, `multilingual`, `modular` (#1343–#1368). Instead of `/commands`, import the
+  grammar modules from the root: `import { toggle } from '@hyperfixi/core'`.
+- **Core's browser bundles** (#1348, #1350, #1352, #1368): `hyperfixi-hx.js`,
+  `hyperfixi-hx-v4.js`, `hyperfixi-hybrid-complete.js`, `hyperfixi-multilingual.js`,
+  `hyperfixi-classic-i18n.js` and the code-split `hyperfixi.mjs`, plus every alias
+  (`hyperfixi-browser.js`, `hyperfixi-hybrid-hx.js`, each `lokascript-*.js`). Only
+  `hyperfixi.js` remains. CDN URLs pinned to 3.x keep working.
+- **Core's embedded htmx layer** (#1342, #1348, #1350): `hx-*` and fixi `fx-*` on core's runtime,
+  `hx-live`, `sse-connect` / `sse-swap`, `ws-connect` / `ws-send`. Load htmx 4 or fixi beside the
+  engine. `hx-live` becomes the engine's `live` block, and SSE and WebSockets are htmx 4's
+  `hx-sse` / `hx-ws`.
+- **Core-only members of `window.hyperfixi`**: `compile`, `compileSync`, `execute`, `setLocale`,
+  `evalLSENode`, `debugControl`, `semanticDebug`, the `hyperfixi:semantic-parse` event,
+  `hyperfixi:debug` logging, `_hyperscript.behaviors.resolve`, and the deprecated
+  `window.lokascript` (#1352, #1355).
+- **Core-only hyperscript syntax** (#1346, #1363, #1365). The engine rejects `has` / `have`,
+  `prepend`, `copy`, `push url` / `replace url`, `process partials`, the `pseudo` keyword, prefix
+  `unless`, bare `beep`, `a ? b : c`, core's `swap <strategy> of X with Y`, `set @a to v on X`,
+  `.debounce(n)` / `.throttle(n)`, `my?.x` and `tell X to …`. A few forms still parse but no longer
+  do what they did, such as `toggle .a on this` and `go forward`. MIGRATION.md gives each form's
+  upstream spelling. The multilingual reader still accepts them all.
+- **`@hyperfixi/core/multilingual`'s class API** (#1345, #1368): `MultilingualHyperscript` (with
+  `parseToAST`, `getAllTranslations`, …), `getMultilingual`, `multilingual`, `LanguageInfo`,
+  `schemaRoleInferrer`. The entry is three async functions: `parse`, `render`, `translate`.
+- **The AOT compiler** (#1364). Its output ran only on a runtime that was never published.
+  `@lokascript/compilation-service` loses `compile()`, `POST /compile`, `CompileResponse`, the
+  compile cache (`SemanticCache`, `getCacheStats`, `clearCache`, `/cache`), `generateTests`'
+  `executionMode` and `generate()`'s `'js'` target. `generate()` now requires `target`
+  (`react` | `vue` | `svelte` | `intent-element`). `@hyperfixi/mcp-server` loses
+  `compile_hyperscript`, `execute_lse`, `lse_to_hyperscript`'s `compile` option and
+  `generate_tests`' `executionMode`, leaving 106 tools. The loop is now `validate_and_compile`
+  (name kept), then repair, then the hyperscript as is in `_="…"`.
+- **`@hyperfixi/vite-plugin`'s compile mode** (#1360). `mode: 'compile'` warns and builds the
+  engine bundle. The exports `CompiledHandler`, `CompileOptions` and
+  `set/clear/hasSemanticParser` are removed.
+- **Smaller removals.** `@hyperfixi/core/reference` loses `availability`, `BundleAvailability`
+  and `getCommandsByAvailability` (#1363). `@hyperfixi/speech` loses `speechPlugin`,
+  `speakCommand`, `askCommand` and `answerCommand`; the engine has `ask` / `answer` (#1358).
+  `@hyperfixi/intent-element` loses its `evalLSENode` fallback (#1356).
+  `@hyperfixi/patterns-reference` loses four rows that held only retired htmx attributes, and
+  `hx-live-with-mutator` is renamed `live-with-handler` (#1348). Of the never-published VS Code
+  extensions, the LokaScript one loses its debugger and the standalone `_hyperscript` one is
+  retired (#1361).
+
+### Deprecated
+
+- **`@hyperfixi/reactivity`, `@hyperfixi/realtime`, `@hyperfixi/components`**: deprecated on npm,
+  last version 3.3.0 (#1358). Use the engine's built-in `live` / `when` / `bind`, htmx 4's
+  `hx-sse` / `hx-ws`, and upstream's component extension.
+- **`@hyperfixi/types-browser`'s `LokaScriptCoreAPI`**: a deprecated alias of `HyperfixiAPI`
+  (#1356).
+
+### Changed
+
+- ⚠ **`@hyperfixi/core` is the engine plus tooling** (#1368). The root is
+  `export * from '@hyperfixi/engine'` and `VERSION`: `register`, `everything` and each grammar
+  module, `api`, `parse`, `evaluate`, `processNode`, `boot`, and the AST types. The engine stays
+  external, so both packages share one grammar. Kept: `/multilingual`, `/ast-utils`,
+  `/reference`, `/metadata`, `/lsp-metadata`, `/browser`.
+- ⚠ **`hyperfixi.js` (`@hyperfixi/core/browser`) is the engine's `hyperfixi-hs.js`**, byte for
+  byte: 34 KB gzipped instead of ~352 KB (#1355). `window.hyperfixi` is `window._hyperscript`,
+  upstream-shaped (`evaluate`, `parse`, `process`, `use`, `config`, `addSourceTransform`). Parse
+  errors are a `hyperscript:parse-error` event on the element plus a `console.error` (#1354).
+- ⚠ **Runtime semantics follow upstream** wherever core's differed. `swap #a with #b` exchanges
+  the elements; `show` / `hide … with *opacity` honour the strategy; `tell` binds `you`, not `me`;
+  `set` on a selector sets every match; and `no ""` is true. MIGRATION.md has the full list.
+- ⚠ **`@hyperfixi/vite-plugin` emits a bundle on `@hyperfixi/engine`** (#1343). There is one
+  tier: the grammar modules the scan finds. It weighs 17.9 KB gzipped for three commands (3.x lite:
+  3.9 KB) and 34.4 KB for everything; 3.x fell back to 352 KB on `fetch`. htmx is not bundled.
+  Non-English scripts are translated as the engine reads them. `devFallback: 'everything'` is new,
+  and `'full'` / `'hybrid-complete'` mean the same. The plugin no longer depends on core.
+- ⚠ **`@hyperfixi/behaviors` runs on the engine** (peer `@hyperfixi/engine`; upstream works too).
+  Each behavior is defined with `host.evaluate(source)` and written in upstream's idioms.
+  Toggleable's `target` parameter is now `targetEl`. `LokaScriptInstance` / `LokaScriptWindow`
+  are now `HyperscriptHost` / `HyperscriptWindow` (#1338).
+- ⚠ **`@hyperfixi/speech` is an engine module** (#1358). Install it with
+  `register(...everything, speak)`. It is ESM-only and peers on the engine. `speak` takes
+  upstream's syntax (`speak <text> [with voice|rate|pitch|volume <x>]…`) and waits for the
+  utterance to end.
+- ⚠ **The localized htmx vocabulary moved** from `@hyperfixi/core/vocab/htmx/{lang}.js` to
+  `@lokascript/htmx-adapter/vocab/{lang}.js`; the data is unchanged (#1349).
+- **`@hyperfixi/intent-element`** renders an intent to English with the page's semantic bundle
+  and runs it through the host's `evaluate` (`NO_RENDERER` without one). It peers on
+  `@hyperfixi/engine` and `@lokascript/semantic` (#1339, #1356).
+- **`@lokascript/semantic` writes upstream's spelling in English** for core-only forms (#1346).
+  For example, `has` becomes `matches`, `prepend` becomes `put … at start of`, and swap strategies
+  become `put … into` / `before` / `after`. This reaches `translate(…, 'en')`,
+  `render(node, 'en')`, both adapters and MCP `translate_to_english`. In `fromSemanticAST`, a
+  handler's `then` chain is now its body (#1359).
+- **The language tools read the engine's parse** (#1356, #1359, #1365).
+  `@lokascript/language-server` and MCP `validate_hyperscript` report the engine's errors
+  (`source: 'engine'`). Hover and symbols come from `@lokascript/semantic`, and some long handlers
+  show fewer commands than in 3.x. Hyperscript mode flags exactly `new X()` and `toggle <element>`.
+  `@lokascript/compilation-service` rejects natural-language input the engine cannot read
+  (`ENGINE_PARSE_ERROR`), and its generated Playwright tests load `hyperfixi-hs.js`. The language
+  server, the MCP server and the compilation service now peer on `@hyperfixi/engine`.
+- **MCP**: `get_bundle_config` recommends `hyperfixi-hs.js`, plus an `adapter` field for
+  non-English. `analyze_complexity` / `analyze_metrics` no longer count every comparison as a
+  decision. The `debug_*` tools point to `log` and `breakpoint`. `UNSUPPORTED_QUERY_LITERAL` is
+  gone (#1350, #1352, #1359, #1361, #1364).
+- **`@hyperfixi/core/reference`, `/lsp-metadata`, `/metadata` describe the engine** (#1355,
+  #1363). They cover its 53 commands, adding `for`, `ask`, `answer` and `beep!`. Examples are in
+  upstream spelling and each is checked to parse; descriptions of core-only semantics (`pick`,
+  `beep`, `swap`) are fixed. `FEATURE_KEYWORDS` gains `install`, `when`, `live` and `bind`, and
+  `bundleInfo` holds one row.
+- **Dependencies.** `@lokascript/i18n`, `@hyperfixi/testing-framework`, `@hyperfixi/vite-plugin`,
+  `@hyperfixi/behaviors`, `@hyperfixi/speech` and `@hyperfixi/intent-element` no longer depend
+  on core. Core drops `@lokascript/intent`, morphlex, tslib and its optional peers. Versions are
+  lockstep, so upgrade `@hyperfixi/*` and `@lokascript/*` together. `@hyperfixi/mcp-server`,
+  `@lokascript/framework` (tests) and `@hyperfixi/server-bridge` (tests) range on
+  `@lokascript/domains ^3.0.1`, the first domains release whose peers accept framework,
+  semantic and intent 4.x (`^3.1.0 || ^4.0.0`).
+
+### Added
+
+- **`@hyperfixi/engine` exports `expr`**, so a grammar module can live in another package
+  (#1358).
+- **`@hyperfixi/core/ast-utils`'s `withEnginePositions`** gives interchange nodes the source
+  spans of the engine's parse (#1359).
+
+### Fixed
+
+- **`@hyperfixi/engine`** accepts upstream's `beep!` command (`beep! a, b`); 3.3.0 rejected it
+  (#1362).
+- **`@hyperfixi/types-browser`** types `window.hyperfixi` / `window._hyperscript` as the engine's
+  `HyperfixiAPI`. 3.3.0 re-exported a `./globals` it never emitted, so `window.hyperfixi` was
+  untyped (#1356).
+- **Semantic browser bundles** (#1351). Single-language and regional bundles (es, ja,
+  east-asian, …) registered no English, so the hyperscript adapter left scripts untranslated. They
+  now register it (+~2.2 KB gzipped) and export `translate`. The lite adapter finds any
+  `LokaScriptSemantic*` global.
+- **`@lokascript/semantic`** (#1338, #1343, #1347). `/core` plus a language module no longer
+  throws "No patterns registered". `on click from (x or me)` parses in th and zh. A `js … end`
+  block no longer ends its handler in ja / ko / hi / tr / qu / bn. An options object's `}` is no
+  longer read as an SOV event name.
+- **Language server and MCP** (#1359, #1363, #1365). `beep!` has hover docs. `set X to`
+  completions offer values. Hyperscript-mode errors land on the form, not line 0. Hover no longer
+  shows a second `on click`.
+
 ## [3.3.0] - 2026-10-02
 
 The first publication of `@hyperfixi/engine`, the hyperscript engine meant to replace the one

package/README.md

@@ -1,11 +1,11 @@
-# @lokascript/types-browser
+# @hyperfixi/types-browser
 
-TypeScript type definitions for LokaScript browser globals.
+TypeScript type definitions for the hyperfixi browser globals.
 
 ## Installation
 
 ```bash
-npm install --save-dev @lokascript/types-browser
+npm install --save-dev @hyperfixi/types-browser
 ```
 
 ## Usage
@@ -15,17 +15,16 @@ Add to your `tsconfig.json`:
 ```json
 {
   "compilerOptions": {
-    "types": ["@lokascript/types-browser"]
+    "types": ["@hyperfixi/types-browser"]
   }
 }
 ```
 
-Now you get full TypeScript autocomplete for browser globals:
+The globals are then typed:
 
 ```typescript
-// Full IDE autocomplete and type safety!
-window.lokascript.execute('toggle .active', document.body);
-window._hyperscript.compile('on click add .highlight');
+window.hyperfixi.evaluate('toggle .active on me', { me: button });
+window._hyperscript.parse('on click add .highlight').errors; // []
 
 window.LokaScriptSemantic.parse('トグル .active', 'ja');
 window.LokaScriptSemantic.translate('toggle .active', 'en', 'ko');
@@ -35,24 +34,36 @@ window.LokaScriptI18n.getProfile('ja');
 
 ## Provided Types
 
-### window.lokascript / window.\_hyperscript
-
-Core LokaScript API (from `lokascript-browser.js` or `lokascript-multilingual.js`):
-
-- `compile(source, options?)` - Compile hyperscript to AST
-- `execute(source, element?, context?)` - Execute hyperscript
-- `parse(source)` - Parse to AST
-- `processNode(node)` - Process single DOM node
-- `process(root?)` - Process entire document
-- `createContext(element?, options?)` - Create execution context
-- `isValidHyperscript(source)` - Validate syntax
-- `version` - Get version string
-- `createRuntime(options?)` - Create runtime instance
+### window.hyperfixi / window.\_hyperscript
+
+One object, `HyperfixiAPI`: the public API of `@hyperfixi/engine`, which its `hyperfixi-hs.js`
+installs (and `@hyperfixi/core`'s `hyperfixi.js`, the same file). It is shaped like upstream
+`_hyperscript`'s:
+
+- `hyperfixi(source, context?)` / `evaluate(source, context?)` — run commands, features or an
+  expression; `context.me` is the element `me` refers to
+- `parse(source)` — parse without running; grammar errors are in `.errors`
+- `process(node)` / `processNode(node)` — initialise the scripted elements under a node
+- `cleanup(element)` — remove what an element's script installed
+- `config` — settings, and the `as <Name>` conversion table
+- `use(plugin)`, `addBeforeProcessHook(hook)`, `addAfterProcessHook(hook)` — upstream's plugin API
+- `addSourceTransform(transform)` — not in upstream: rewrite a script as it is read
+- `version`
+
+The package's typecheck checks the engine's own `api` against `HyperfixiAPI`, so the two cannot
+drift apart.
+
+> **4.0:** until then `window.hyperfixi` was typed as `@hyperfixi/core`'s own API (`compile`,
+> `compileSync`, `execute`, `createContext`, `evalHyperScript`, …). `hyperfixi.js` is the engine's
+> file now, and none of those exist on it: `compileSync(code)` → `parse(code).errors`;
+> `execute(code, el)` → `evaluate(code, { me: el })`; `compile(code, { language })` → load
+> `@lokascript/hyperscript-adapter` beside a semantic bundle. `window.lokascript` is gone.
+> `LokaScriptCoreAPI` remains as a deprecated alias of `HyperfixiAPI`. (3.x's published
+> `index.d.ts` also never reached its window augmentation: `globals.d.ts` was not emitted.)
 
 ### window.LokaScriptSemantic
 
-Semantic parsing and translation API (from `@lokascript/semantic`'s
-`dist/browser.global.js`):
+Semantic parsing and translation API (from `@lokascript/semantic`'s browser bundles):
 
 - `parse(source, language)` - Parse in any of 24 languages
 - `translate(source, fromLang, toLang)` - Translate between languages
@@ -76,16 +87,12 @@ Language vocabulary API (from `lokascript-i18n.min.js`):
 ## Browser Bundle Loading
 
 ```html
-<!-- Load LokaScript browser bundles -->
-<script src="https://cdn.jsdelivr.net/npm/@hyperfixi/core/dist/hyperfixi.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@hyperfixi/engine/dist/hyperfixi-hs.js"></script>
 <script src="https://cdn.jsdelivr.net/npm/@lokascript/semantic/dist/browser.global.js"></script>
 <script src="https://cdn.jsdelivr.net/npm/@lokascript/i18n/dist/lokascript-i18n.min.js"></script>
 
-<!-- Now use with full TypeScript support -->
 <script>
-  // TypeScript knows about these globals!
-  window.lokascript.execute('toggle .active');
-  window.LokaScriptSemantic.parse('トグル .active', 'ja');
+  window.hyperfixi.evaluate('add .ready to me', { me: document.body });
   window.LokaScriptSemantic.translate('toggle .active', 'en', 'ja');
 </script>
 ```

package/dist/core-api.d.ts

@@ -1,213 +1,124 @@
 /**
- * Type definitions for HyperFixi Core browser API
+ * Type definitions for the hyperscript host on `window.hyperfixi` and `window._hyperscript`.
+ *
+ * Both globals are one object: `@hyperfixi/engine`'s public API, which the engine's
+ * `hyperfixi-hs.js` installs, and which `@hyperfixi/core` ships as `hyperfixi.js` (the same
+ * file, since Phase C3 of the engine cutover). It is shaped like upstream `_hyperscript`'s
+ * public object, so upstream plugins can use it, plus one hook upstream lacks
+ * (`addSourceTransform`). `test/engine-api.check.ts` checks the engine's own `api` against
+ * this interface, so the two cannot drift apart.
+ *
+ * (Until then `hyperfixi.js` was core's own bundle, and `window.hyperfixi` had core's API:
+ * `compile`, `compileSync`, `execute`, `createContext`, `evalHyperScript`, … — none of which
+ * the engine has. Those types are gone; see `HyperfixiAPI` for what replaced each.)
  */
-/**
- * HyperFixi core API exposed on window.hyperfixi
- */
-export interface LokaScriptCoreAPI {
-    /**
-     * Synchronously compile hyperscript code to AST (API v2).
-     * @since API v2
-     */
-    compileSync(code: string, options?: NewCompileOptions): CompileResult;
-    /**
-     * Asynchronously compile hyperscript code (handles all 13 languages) (API v2).
-     * @since API v2
-     */
-    compile(code: string, options?: NewCompileOptions): Promise<CompileResult>;
-    /**
-     * Compile and execute hyperscript in one step (API v2).
-     * @since API v2
-     */
-    eval(code: string, contextOrElement?: any): Promise<any>;
-    /**
-     * Validate hyperscript syntax and return detailed errors (API v2).
-     * @since API v2
-     */
-    validate(code: string, options?: NewCompileOptions): Promise<ValidateResult>;
-    /**
-     * Create execution context with optional parent (unified signature, API v2).
-     * @since API v2
-     */
-    createContext(element?: Element | null, parent?: any): any;
-    /**
-     * Evaluate hyperscript string directly
-     */
-    evalHyperScript(code: string, element?: Element): any;
-    /**
-     * Async evaluation of hyperscript
-     */
-    evalHyperScriptAsync(code: string, element?: Element): Promise<any>;
-    /**
-     * Smart evaluation with automatic context detection
-     */
-    evalHyperScriptSmart(code: string): Promise<any>;
-    /**
-     * Compile multilingual hyperscript code
-     * @deprecated Use compile() with options.language instead
-     */
-    compileMultilingual(code: string, language: string, options?: CompileOptions): CompilationResult;
-    /**
-     * Execute hyperscript code
-     */
-    execute(code: string, element?: Element, options?: ExecuteOptions): Promise<any>;
-    /**
-     * Run hyperscript code (alias for execute)
-     * @deprecated Use eval() instead
-     */
-    run(code: string, element?: Element, options?: ExecuteOptions): Promise<any>;
-    /**
-     * Create child execution context
-     * @deprecated Use createContext(element, parent) instead
-     */
-    createChildContext(parent: any, element?: Element): any;
-    /**
-     * Validate hyperscript syntax (returns boolean)
-     * @deprecated Use validate() instead (returns detailed result)
-     */
-    isValidHyperscript(code: string): boolean;
-    /**
-     * Create runtime instance
-     */
-    createRuntime(options?: RuntimeOptions): any;
-    /**
-     * Process DOM node
-     */
-    processNode(node: Node): void;
-    /**
-     * Process DOM node (alias)
-     */
-    process(node: Node): void;
-    /**
-     * Tokenize hyperscript code
-     */
-    tokenize(code: string): any[];
-    /**
-     * Low-level parser access
-     */
-    Parser: any;
-    /**
-     * Low-level runtime access
-     */
-    Runtime: any;
-    /**
-     * Attribute processor
-     */
-    attributeProcessor: any;
-    /**
-     * Debug utilities
-     */
-    debug: {
-        enableDebugLogging(): void;
-        disableDebugLogging(): void;
-    };
-    /**
-     * Style batcher utility
-     */
-    styleBatcher: any;
-    /**
-     * Object pool utility
-     */
-    ObjectPool: any;
-    /**
-     * Semantic parsing utilities
-     */
-    semantic?: {
-        parse(code: string, language: string): any;
-        translate(code: string, fromLang: string, toLang: string): string | null;
-        buildAST(node: any): any;
-    };
-    /**
-     * Semantic debug utilities
-     */
-    semanticDebug?: any;
-    /**
-     * Version string
-     */
-    version: string;
-}
-export interface CompileOptions {
-    language?: string;
-    strict?: boolean;
-    [key: string]: any;
+/** The context `evaluate` runs its source in. Every field is optional. */
+export interface HyperscriptContext {
+    /** What `me` / `my` / `I` refer to (default: `document.body`). */
+    me?: unknown;
+    you?: unknown;
+    /** `it` / `result`. */
+    result?: unknown;
+    event?: unknown;
+    target?: unknown;
+    detail?: unknown;
+    sender?: unknown;
+    body?: unknown;
+    /** Local variables, by name. */
+    locals?: Record<string, unknown>;
 }
-export interface CompilationResult {
-    success: boolean;
-    code?: any;
-    error?: Error;
-    [key: string]: any;
-}
-export interface ExecuteOptions {
-    context?: any;
-    element?: Element;
-    [key: string]: any;
+/** The token a parse error points at. */
+export interface HyperscriptToken {
+    type: string;
+    value: string;
+    /** Offsets into the source. */
+    start: number;
+    end: number;
+    /** 1-based line, 0-based column. */
+    line: number;
+    column: number;
 }
-export interface ContextOptions {
-    element?: Element;
-    globals?: Record<string, any>;
-    [key: string]: any;
+/** A grammar error, as `parse` reports it and as the `hyperscript:parse-error` event carries it. */
+export interface HyperscriptParseError {
+    message: string;
+    token: HyperscriptToken;
+    source: string;
+    /** The words the parser would have accepted, when it knows. */
+    expected?: string[];
+    /** What the author wrote, when a source transform rewrote the script before it was parsed. */
+    written?: string;
 }
-export interface RuntimeOptions {
-    [key: string]: any;
+/** `parse`'s result: the parsed node in upstream's shape, with its `errors` (empty when it parsed). */
+export interface HyperscriptParseResult {
+    errors: HyperscriptParseError[];
 }
-export type EvalHyperScriptFunction = (code: string, element?: Element) => any;
-export type EvalHyperScriptAsyncFunction = (code: string, element?: Element) => Promise<any>;
-export type EvalHyperScriptSmartFunction = (code: string) => Promise<any>;
+/** A root `processNode` initialises: hooks receive it before and after. */
+export type HyperscriptProcessRoot = Element | Document | DocumentFragment;
 /**
- * Compilation result (API v2)
+ * A plugin's rewrite of a script, applied as the script is read; the element keeps the text its
+ * author wrote. Return nothing to leave the script as it is.
  */
-export interface CompileResult {
-    /** Whether compilation succeeded */
-    ok: boolean;
-    /** Compiled AST (only present if ok=true) */
-    ast?: any;
-    /** Compilation errors (only present if ok=false) */
-    errors?: CompileError[];
-    /** Compilation metadata */
-    meta: {
-        /** Parser used: semantic or traditional */
-        parser: 'semantic' | 'traditional';
-        /** Confidence score (0-1) if semantic parser was used */
-        confidence?: number;
-        /** Language code */
-        language: string;
-        /** Compilation time in milliseconds */
-        timeMs: number;
-        /** Whether direct path was taken (no fallback) */
-        directPath?: boolean;
+export type HyperscriptSourceTransform = (source: string, element: Element) => string | null | undefined;
+/** `config`: upstream's settings, and the table `as <Name>` conversions read. */
+export interface HyperscriptConfig {
+    /** Attributes that hold a script (default `'_, script, data-script'`). */
+    attributes: string;
+    defaultTransition: string;
+    disableSelector: string;
+    /** The strategy `hide` / `show` / `toggle` use when none is named (`display` if unset). */
+    defaultHideShowStrategy?: string;
+    /** Extra strategies, by name. */
+    hideShowStrategies: Record<string, (op: 'hide' | 'show' | 'toggle', elt: HTMLElement, arg?: string) => void>;
+    /** `fetch` throws when the response status matches one of these. */
+    fetchThrowsOn: RegExp[];
+    /** `as <Name>` conversions, by name; `dynamicResolvers` handle names with arguments. */
+    conversions: Record<string, (value: unknown) => unknown> & {
+        dynamicResolvers: ((name: string, value: unknown) => unknown)[];
     };
 }
 /**
- * Compilation error (API v2)
- */
-export interface CompileError {
-    /** Error message */
-    message: string;
-    /** Line number where error occurred */
-    line: number;
-    /** Column number where error occurred */
-    column: number;
-    /** Optional suggestion for fixing the error */
-    suggestion?: string;
-}
-/**
- * Compilation options (API v2)
+ * `window.hyperfixi` / `window._hyperscript`. Callable: `hyperfixi(source, context?)` is
+ * `hyperfixi.evaluate(source, context?)`.
+ *
+ * Replacing core 3.x's API: `compileSync(code)` → `parse(code).errors`;
+ * `eval(code, element)` / `execute(code, element)` → `evaluate(code, { me: element })`;
+ * `processNode(node)` is unchanged; `compile(code, { language })` → load
+ * `@lokascript/hyperscript-adapter` beside a semantic bundle, which translates each script as
+ * the engine reads it.
  */
-export interface NewCompileOptions {
-    /** Language code (default: 'en') */
-    language?: string;
-    /** Minimum confidence for semantic parsing (0-1, default: 0.5) */
-    confidenceThreshold?: number;
-    /** Force traditional parser, skip semantic analysis */
-    traditional?: boolean;
-}
-/**
- * Validation result (API v2)
- */
-export interface ValidateResult {
-    /** Whether code is valid */
-    valid: boolean;
-    /** Validation errors (only present if valid=false) */
-    errors?: CompileError[];
+export interface HyperfixiAPI {
+    (source: string, context?: HyperscriptContext): unknown;
+    /**
+     * Run source: commands, features (installed on `document.body`) or one expression.
+     * Synchronous unless the source itself waits on something; then it returns a promise.
+     * A parse error throws.
+     */
+    evaluate(source: string, context?: HyperscriptContext): unknown;
+    /** Parse without running. A grammar error is reported in `errors`; a tokenizer error throws. */
+    parse(source: string): HyperscriptParseResult;
+    /** Initialise every scripted element under a node; elements already initialised are skipped. */
+    process(node: unknown): void;
+    /** Upstream's older name for `process`. */
+    processNode(node: unknown): void;
+    /** Remove everything an element's script installed: listeners, observers, timers, state. */
+    cleanup(element: Element): void;
+    config: HyperscriptConfig;
+    /** `use(plugin)`: the plugin receives this object (upstream's plugin API). */
+    use(plugin: (hyperscript: unknown) => void): void;
+    addBeforeProcessHook(hook: (root: HyperscriptProcessRoot) => void): void;
+    addAfterProcessHook(hook: (root: HyperscriptProcessRoot) => void): void;
+    /** Not in upstream: rewrite a script as it is read, leaving the attribute as written. */
+    addSourceTransform(transform: HyperscriptSourceTransform): void;
+    /** The part of upstream's `internals` that pages and tests reach for. */
+    internals: {
+        runtime: {
+            cleanup(element: Element): void;
+            processNode(node: unknown): void;
+        };
+    };
+    /** The engine's package version (`'dev'` when built from source without one). */
+    version: string;
 }
+/** @deprecated The 3.x name; `window.hyperfixi` is a {@link HyperfixiAPI} since 4.0. */
+export type LokaScriptCoreAPI = HyperfixiAPI;
 //# sourceMappingURL=core-api.d.ts.map

package/dist/core-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core-api.d.ts","sourceRoot":"","sources":["../src/core-api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"core-api.d.ts","sourceRoot":"","sources":["../src/core-api.ts"],"names":[],"mappings":"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"}