@hyperfixi/engine 3.3.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2025 LokaScript Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,272 @@
+# @hyperfixi/engine
+
+A hyperscript engine written against upstream `_hyperscript`'s source as the specification and
+upstream's own test suite as the acceptance oracle. It is typed (`tsc --strict`, no `any`),
+synchronous until a script really waits on something, and built from modules, so a bundle
+contains the commands it registers and nothing else.
+
+It is meant to replace the engine in `packages/core`, and is published as its own package
+(since 2026-10-02). Nothing else in the repository depends on it at run time yet; the migration
+plan is `~/.claude/plans/engine-replaces-core.md`.
+
+## Install
+
+The script-tag bundle, hyperscript and nothing else (34.1 KB gzipped). It installs as
+`window._hyperscript` and `window.hyperfixi`, and reads the document when it is ready:
+
+```html
+<script src="https://unpkg.com/@hyperfixi/engine/dist/hyperfixi-hs.js"></script>
+<button _="on click toggle .active on me">Toggle</button>
+```
+
+Or, with a bundler, build an engine from the modules a page needs:
+
+```sh
+npm install @hyperfixi/engine
+```
+
+## Use
+
+```ts
+import { register, boot, on, add, remove, toggle } from '@hyperfixi/engine';
+
+register(on, add, remove, toggle); // this engine knows `on`, `add`, `remove`, `toggle`
+boot(); // install as window._hyperscript and initialise the document
+```
+
+A module is a function `(g: Grammar) => void` that adds its rules to the grammar: a command, a
+feature, or an optional expression kind. A rule that is not registered does not exist, and a
+script that uses it fails with a parse error that names the token. `src/bundles/full.ts` is the
+list of every module.
+
+The public object is shaped like upstream's `_hyperscript` (`evaluate`, `parse`, `process`,
+`config`, `use(plugin)`, `addBeforeProcessHook`), so a plugin written for upstream's public API
+can be used on it; the multilingual adapter is. It adds one hook upstream lacks:
+
+```ts
+_hyperscript.addSourceTransform((source, element) => english);
+```
+
+A script is rewritten as it is read. The element keeps the text its author wrote, and a parse
+error in the rewritten script carries that text (`error.written`). `@lokascript/hyperscript-adapter`
+uses the hook when the host has it.
+
+## Layout
+
+| File                                                             | What it holds                                                                                                                                                |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `src/index.ts`                                                   | The library entry: the engine functions, the node types, every module                                                                                        |
+| `src/tokenizer.ts`, `src/parser.ts`                              | Lexer, token stream, grammar registry, parse errors                                                                                                          |
+| `src/expressions.ts`                                             | The expression chain and the core expression kinds                                                                                                           |
+| `src/expressions-extra.ts`, `src/conversions.ts`                 | Optional modules: positional, `closest`, collection operators, type checks; the less common `as` conversions                                                 |
+| `src/statements.ts`                                              | Commands, command lists, programs                                                                                                                            |
+| `src/runtime.ts`, `src/engine.ts`                                | Contexts, scopes, collections, block execution; DOM init, cleanup, public API                                                                                |
+| `src/on.ts`, `src/features.ts`                                   | Features: `on`; `def`, `init`, `behavior`, `install`, top-level `set`                                                                                        |
+| `src/reactivity.ts`, `src/templates.ts`, `src/live-templates.ts` | Optional: `when` / `live` / `bind`; `render` and template text; live templates                                                                               |
+| `src/commands/*`                                                 | 52 command keywords, one module export each                                                                                                                  |
+| `src/additions.ts`                                               | The two forms upstream does not have: `new X()` and `toggle <element>`                                                                                       |
+| `src/bundles/*`                                                  | Browser bundle entries. `hyperfixi-hs` is the script-tag bundle; `full` is the same modules, for the gate; `core`, `minimal`, `common` exist to measure size |
+| `upstream-suite/`                                                | The acceptance gate: upstream's Playwright suite (vendored) against a bundle                                                                                 |
+| `tests/`                                                         | This package's own tests (`src/additions.ts`, and regressions upstream's tests did not show), in the form of upstream's and on the same fixtures             |
+| `tools/probe.mts`                                                | One source on this engine and on upstream, side by side, on the value matrix's fixture                                                                       |
+
+A node is typed data plus the closure that runs it, bound when the node is parsed: an
+expression has `ev`, a command has `run`, a feature has `install`. Control flow is a value a
+command returns (`return`, `break`, `continue`), not an exception.
+
+## Commands
+
+```bash
+npm run build --prefix packages/engine          # dist/: library, bundles, declarations; prints sizes
+npm run typecheck --prefix packages/engine
+npm run test:upstream --prefix packages/engine  # the gate (needs a build; about 30 s)
+npm run test:own --prefix packages/engine       # additions and regressions (needs a build; 2 s)
+npm run cost --prefix packages/engine           # what each module costs in the full bundle
+
+# Any engine bundle can be scored on the same suite:
+node packages/engine/upstream-suite/run.mjs --bundle <bundle.js> --fails
+
+# One source on this engine and on upstream, side by side:
+npx tsx packages/engine/tools/probe.mts '<source>'
+
+# What this engine reads of the sources this repository ships, beside core and upstream:
+npx tsx packages/engine/tools/shipped-sources.mts
+```
+
+## The gates
+
+**Upstream's suite.** `test:upstream` runs upstream's own tests (`upstream-suite/vendor/`,
+release 0.9.93, the one this repository's other gates use) against `dist/full.js`. The tests
+that fail must be exactly the ones listed in `upstream-suite/known-failures.json`. A new failure
+fails the gate. So does a listed test that now passes: prune it with
+`npm run test:upstream:update` in the same change, so the list stays what does not pass. CI runs
+it in the `browser-tests` job.
+
+**The package's own tests.** `test:own` runs `tests/` against the same bundle, for the two forms
+upstream has no tests for. Every one must pass. On upstream's own bundle 2 of the 21 pass (the
+two that check an upstream form still reads as it did), which is what shows the rest test the
+additions. `tests/regressions.js` holds the other kind: places where this engine differed from
+upstream and upstream's tests did not show it (each of those passes on upstream). CI runs both
+after the upstream suite.
+
+**The multilingual gates**, in the packages that own them:
+
+- The value matrix (`packages/testing-framework`, `value-matrix.ts`) has an `eng` lane, the
+  English source on this engine, and a `<lang>/eng` lane per language: the adapter's English,
+  the same string the `/up` lane runs on upstream, on this engine.
+- `engine-parser-parity.test.ts` (same package) puts every string the canonical-validity gates
+  ask upstream's parser about to this engine's parser; the two must agree.
+- `packages/hyperscript-adapter/test/engine-host.test.ts` hosts the real plugin on this engine.
+
+**The shipped-sources gates**, also in `packages/testing-framework`:
+
+- `shipped-sources-engine.test.ts` lists the sources this repository ships (`examples/`, the doc
+  trees) that `packages/core` compiles and this engine rejects
+  (`baselines/shipped-sources-engine.json`). A new one fails; so does a listed one that now
+  parses. It is empty when replacing core's engine breaks no shipped page.
+- `shipped-examples-execution.test.ts` has an engine lane: every example handler upstream accepts
+  is run on upstream and on this engine, in jsdom, and the DOM effects must match. Measured
+  2026-10-01: 134 handlers, 89 matches with an effect, 44 with none on either, 1 difference
+  (upstream reads a stale `document` in that harness). `packages/core` differs on 31.
+
+## Measured (2026-10-01, upstream 0.9.93)
+
+|                        | this engine (`full` bundle) | `hyperfixi.js`          | upstream |
+| ---------------------- | --------------------------- | ----------------------- | -------- |
+| Whole suite (1,467)    | 1,401                       | 826                     | 1,466    |
+| Command tests (516)    | 516                         | 306                     | 516      |
+| Expression tests (459) | 457                         | 371                     | 459      |
+| Feature tests (254)    | 237                         | 100                     | 253      |
+| Core tests (190)       | 143                         | 49                      | 190      |
+| Template tests (48)    | 48                          | 0                       | 48       |
+| Size, gzipped          | 34.1 KB with every module   | 92 KB engine-only build | 45.8 KB  |
+
+Bundle sizes, gzipped: `minimal` (`on` + add / remove / toggle) 16.3 KB, `common` (15 everyday
+commands) 18.4 KB, `full` 34.1 KB, `core` (no commands) 13.8 KB.
+
+## The script-tag bundle: `hyperfixi-hs.js`
+
+`dist/hyperfixi-hs.js` (minified, 34.1 KB gzipped; `hyperfixi-hs.dev.js` is the readable build) is the first product on this engine:
+hyperscript and nothing else, every module, no htmx attributes, English only. It installs
+`window._hyperscript`, as upstream does, and the same object as `window.hyperfixi`. The name
+pairs with `hyperfixi-hx.js` (hyperscript plus htmx); `hyperfixi.js` is everything.
+
+Thirty-six example pages load it instead of `packages/core/dist/hyperfixi.js` (2026-10-02):
+the pages that need only hyperscript. (Twenty-one by a script tag; fifteen through the
+examples' loader, `data-default="hs"`, so that `?bundle=` still switches them.) Core's
+Playwright suites run them, and the bundle is a column of the bundle-compatibility matrix
+(`?bundle=hs` in the examples' loader). No page needed an API shim: `processNode` is upstream's
+name too, and the other `hyperfixi.*` calls were core debugging code. The multilingual demo
+pages are among the thirty-six: their handlers are English, and what they translate for display
+comes from the i18n or semantic bundle, loaded beside the engine. What keeps the other pages on
+`hyperfixi.js`: the behaviors resolver (4), the intent element (4), core's own debug pages (2),
+`<script type="text/hyperscript" for="…">` (1), partial validation (1), htmx attributes (1),
+and the history commands. One behavior of core's is not in this engine, by decision
+(2026-10-02): `increment #count` on core counts in the element's text, where upstream and this
+engine want `increment #count's textContent`. The examples write the second, which every
+bundle runs to the same count (the bundle matrix's Counter row).
+
+The 66 known failures: upstream's internal-API surface (`internals.tokenizer`,
+`evalStatically`, source info, error collection: 47), sockets and workers (17, upstream
+extensions that are not built), and two collection-expression tests that need upstream's
+component extension. Upstream's one failure is a test that expects its worker extension to be
+absent.
+
+As a host for the multilingual text path (semantic renders a translation, the adapter's
+`preprocess` turns it back into English, the engine runs the English):
+
+- **Value matrix.** 4,205 cells. English on this engine gives the oracle's value in every cell.
+  Through the adapter in 23 languages, 96,640 of 96,643 (cell, language) pairs do, and the two
+  hosts agree on every pair: the three that miss are the accepted Italian `di` ambiguity, and
+  they miss on upstream too. (`packages/core` misses 8 cells in English and 187 pairs on its
+  direct path.)
+- **Parser parity.** Of the 273 distinct English strings the canonical-validity gates put to
+  upstream's parser, the two parsers disagree on none.
+- Of the 168 corpus rows, 151 parse on both engines and 17 on neither; none parses on one
+  engine only. Fifteen of the 17 are markup or extension rows (components, `sse-*` / `ws-*` /
+  `hx-live`, sockets, workers, event sources, `intercept`) and one is valid nowhere. Two are
+  syntax only `packages/core` has: `as FormData` (fetch-formdata) and `swap … using view
+transition` (swap-view-transition). Nine more were, until the rows were rewritten in
+  upstream's spelling on 2026-10-01.
+- **The adapter's plugin** in six languages: the script runs and the attribute stays as
+  written. On upstream the plugin has to rewrite the attribute.
+
+## Against what this repository ships
+
+`npx tsx packages/engine/tools/shipped-sources.mts` puts every hyperscript source in
+`examples/` and the doc trees (the shipped-sources gate's collection: 386 sources, 336
+distinct) to three parsers. Measured 2026-10-01:
+
+- upstream accepts 272, this engine 309, `packages/core` 320;
+- **12 sources that core accepts are rejected here**: the eleven handlers that use core's
+  history commands (`push url`, `replace url`), which wait for the htmx decision, and the
+  `hyperfixi-hx.js` example in `docs/BROWSER_BUNDLES.md`, which is written in the hybrid
+  parser's own dialect (`on click.debounce(300)`, `me has .loading`).
+
+It was 78 when first measured. The examples and docs were moved to upstream's spellings where
+upstream has one (`put … into` for core's `swap` strategies, `debounced at 300ms`,
+`start view transition … end`, `morph … to`, `toggle *display of`, `descending`, …: each
+rewrite was run on core, upstream and this engine, to the same DOM), and two forms were added
+here (below).
+
+A parse-level count understates a difference: a source can parse and run differently.
+`set t to new Date().getDay()` parses on upstream (`new` is a variable there, the call a second
+command) and fails when it runs; `swap afterBegin of #list with html` is upstream's exchange of
+two values and inserts nothing. The comparison that counts is the DOM a handler leaves
+(`shipped-examples-execution` in `packages/testing-framework`).
+
+## Differences from upstream
+
+Three, all recorded here and nowhere silent.
+
+**Two additions** (`src/additions.ts`, decided 2026-10-01), forms `packages/core` has and the
+shipped examples use. Each is its own module, and neither changes how an upstream script reads:
+upstream's suite passes the same tests with them registered as without.
+
+- `new Date()`, `new Intl.NumberFormat('en')`, `(new Date()).getDay()`: a constructor call as
+  an expression. `new` is still an ordinary name unless a constructor call follows it. Upstream
+  has the `make a Date` command and no expression. 0.20 KB.
+- `toggle #dialog`, `toggle #dialog modal` (or `as modal`), `toggle #details`: open what is
+  closed and close what is open, for a dialog, a details element (or its summary), a popover
+  and a select. Upstream rejects `toggle <expression>` unless `between` follows; that form is
+  unchanged. 0.21 KB.
+
+**One looser reading**, found by the measurement above: `my @id as String` (an attribute read
+through `my` / `its` / `your`, then a conversion or any further access). Upstream rejects it,
+because its attribute-access rule does not continue the expression chain as every other access
+does; the possessive form `#a's @title as String` works on both. This engine continues the
+chain. It is kept because the stricter reading looks like an upstream slip and a shipped
+example uses the form (`its @data-stock as Number > 0`).
+
+Considered and not added: core's `swap` strategies (upstream's `swap` means something else),
+`copy`, a `? :` conditional, `.debounce(n)`, `has`, prefix `unless`, `set @a to v on <target>`,
+`sorted by … desc`. `push url` / `replace url` are undecided.
+
+## Where the bytes are
+
+`npm run cost` rebuilds the full bundle without each registered module and prints the
+difference. Of the 34.1 KB: the fixed core (tokenizer, parser, the core expression kinds,
+runtime, engine) is 12.2 KB; `on` is 1.6; the optional modules add up to 15.1; code that
+several modules share is 5.2. The largest modules: `expressionsExtra` 1.5, `reactivity` 1.3,
+`render` 1.0, `repeat` 0.8, `toggle` 0.8, `fetch` 0.7, `pick` 0.7. A simple command costs 20 to
+190 bytes (`throw` 18, `get` 53, `log` 73, `send` 101, `append` 189).
+
+Three ideas for the command layer were measured. None is worth doing for size:
+
+| Idea                                                              | Minified  | Gzipped                                                                     |
+| ----------------------------------------------------------------- | --------- | --------------------------------------------------------------------------- |
+| Share the class / attribute handling of `add`, `remove`, `toggle` | −188      | −4 (`minimal`), +6 (all)                                                    |
+| Drop the descriptive fields from node literals (65 of them)       | −1,459    | −566 (all), −177 (`minimal`)                                                |
+| A table-driven grammar for the simple commands                    | not built | an estimate: under 200, since the eight simplest commands cost 700 in total |
+
+Gzip already removes repeated text, so removing duplication between commands shrinks the
+minified file and not the download. The first row is kept because it is less code. The second
+saves 1.7 % and would cost the typed half of each node. The third would have to parse those
+commands for nothing to break even.
+
+The fixed core is three quarters of a small bundle. The comparison operators (`is`, `matches`,
+`is greater than`, `starts with`, …) are 1.25 KB of it and the math operators 0.15 KB, measured
+by stubbing them out. They stay in the core by decision (2026-10-01): a bundle without them
+would reject `when it matches .x`, and simpler bundles were preferred to smaller ones.
+
+Source: 8,100 lines, one documented type assertion (`num` in `src/util.ts`).

package/dist/additions.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Syntax upstream `_hyperscript` does not have. Everything else in this engine
+ * follows upstream's source; these two forms come from `packages/core`, are used
+ * by the examples this repository ships, and were kept by decision (2026-10-01).
+ * Each is an optional module, and neither changes how an upstream script reads:
+ *
+ * - `construct`: `new Date()`, `new Intl.NumberFormat('en')`. Upstream has the
+ *   `make a Date` command and no expression; there, `set t to new Date().getDay()`
+ *   parses (`new` is a variable, the call a second command) and fails when it runs.
+ * - `toggleElement`: `toggle #dialog`, `toggle #dialog modal`, `toggle #details`.
+ *   Upstream rejects `toggle <expression>` without `between`.
+ */
+import type { Cmd, Expr } from './ast';
+import type { Grammar } from './parser';
+export interface ConstructNode extends Expr {
+    type: 'newExpression';
+    /** `Intl.NumberFormat` is `['Intl', 'NumberFormat']`. */
+    path: string[];
+    args: Expr[];
+}
+/** `new <Constructor>(<args>)`: construct an object, as JavaScript's `new` does. */
+export declare function construct(g: Grammar): void;
+export interface ToggleElementNode extends Cmd {
+    type: 'toggleElementCommand';
+    target: Expr;
+    /** `toggle #d modal` / `toggle #d as modal`: open with `showModal()`. */
+    modal: boolean;
+}
+/** `toggle <element> [modal | as modal]`: the form `toggle` takes when no `between` follows. */
+export declare function toggleElement(g: Grammar): void;

package/dist/ast.d.ts

@@ -0,0 +1,277 @@
+/**
+ * The engine's node types.
+ *
+ * A node is plain typed data plus the closure that runs it. The closure is bound
+ * once, when the node is parsed, so execution never re-reads syntax: an
+ * expression has `ev`, a command has `run`, a feature has `install`. Every
+ * member of the unions below is discriminated by `type`.
+ */
+import type { MaybeP } from './util';
+export interface Meta {
+    /** The element whose script this is. */
+    owner: unknown;
+    feature?: Feature;
+    /** The event, while an `on …[filter]` expression is being evaluated. */
+    context?: unknown;
+    returned?: boolean;
+    returnValue?: unknown;
+    /** While a template renders: its output so far, and what each of its loops iterates over. */
+    template?: {
+        out: string[];
+        loops: Record<string, LoopScope>;
+    };
+}
+/** A loop in a template, kept so an element in its output can take the loop's variables. */
+export interface LoopScope {
+    identifier?: string;
+    indexIdentifier?: string;
+    source: unknown;
+}
+export interface Ctx {
+    me: unknown;
+    you: unknown;
+    result: unknown;
+    /** The element under test inside a `when` / `where` clause; `it` reads it first. */
+    beingTested: unknown;
+    event: unknown;
+    target: unknown;
+    detail: unknown;
+    sender: unknown;
+    body: unknown;
+    locals: Record<string, unknown>;
+    meta: Meta;
+}
+export type Signal = {
+    k: 'return';
+    value: unknown;
+} | {
+    k: 'break';
+} | {
+    k: 'continue';
+};
+export type Completion = Signal | void;
+export interface Node {
+    type: string;
+    /** Source offsets, `[start, end)`. */
+    start: number;
+    end: number;
+}
+/**
+ * What every expression has. The optional members are the small protocol other
+ * grammar rules read without knowing the concrete kind: a selector-like value
+ * exposes `css`, a chained access exposes its `root`, and an assignable
+ * expression has `lhs` (evaluate what the write needs) and `put` (do the write).
+ */
+export interface Expr extends Node {
+    ev(ctx: Ctx): unknown;
+    lhs?(ctx: Ctx): unknown;
+    put?(ctx: Ctx, lhs: unknown, value: unknown): void;
+    del?(ctx: Ctx, lhs: unknown): void;
+    /** The value, for an expression that needs no context (a literal, `200ms`). */
+    stat?(): unknown;
+    css?: string;
+    root?: Expr;
+    /** Symbol, attribute or style name. */
+    name?: string;
+    /** Property name of a property access. */
+    prop?: string;
+    /** On a `where` clause inside `for x in …`: the loop variable each item is bound to. */
+    varName?: string;
+}
+export type Scope = 'local' | 'element' | 'global' | 'inherited';
+export interface SymbolNode extends Expr {
+    type: 'symbol';
+    name: string;
+    scope: Scope;
+}
+export interface LiteralNode extends Expr {
+    type: 'boolean' | 'null' | 'number';
+    value: boolean | null | number;
+}
+export interface StringNode extends Expr {
+    type: 'string';
+    value: string;
+    /** Present on a backtick string: literal text interleaved with expressions. */
+    parts?: (string | Expr)[];
+}
+export interface ArrayNode extends Expr {
+    type: 'arrayLiteral';
+    values: Expr[];
+}
+export interface ObjectNode extends Expr {
+    type: 'objectLiteral';
+    keys: (string | Expr)[];
+    values: Expr[];
+}
+export interface NamedArgsNode extends Expr {
+    type: 'namedArgumentList';
+    names: string[];
+    values: Expr[];
+}
+export interface ParenNode extends Expr {
+    type: 'parenthesized';
+    expr: Expr;
+}
+export interface IdRefNode extends Expr {
+    type: 'idRef';
+    /** Absent on `#{expr}`. */
+    value?: string;
+    expr?: Expr;
+}
+export interface ClassRefNode extends Expr {
+    type: 'classRef';
+    /** Absent on `.{expr}`. */
+    className?: string;
+    expr?: Expr;
+}
+export interface QueryRefNode extends Expr {
+    type: 'queryRef';
+    css: string;
+    parts?: (string | Expr)[];
+}
+export interface AttributeRefNode extends Expr {
+    type: 'attributeRef';
+    name: string;
+    css: string;
+    value?: string;
+}
+export interface StyleRefNode extends Expr {
+    type: 'styleRef' | 'computedStyleRef';
+    name: string;
+}
+export interface StyleLiteralNode extends Expr {
+    type: 'styleLiteral';
+    parts: string[];
+    exprs: Expr[];
+}
+export interface ImplicitMeNode extends Expr {
+    type: 'implicitMeTarget';
+}
+export interface PathNode extends Expr {
+    type: 'dotOrColonPath' | 'eventName';
+    value: string;
+}
+export interface PropertyAccessNode extends Expr {
+    type: 'propertyAccess';
+    root: Expr;
+    prop: string;
+}
+export interface OfNode extends Expr {
+    type: 'ofExpression';
+    root: Expr;
+    name: string;
+    kind: 'property' | 'attribute' | 'style' | 'computed';
+}
+export interface PossessiveNode extends Expr {
+    type: 'possessive';
+    root: Expr;
+    prop?: string;
+    attribute?: AttributeRefNode | StyleRefNode;
+}
+export interface InNode extends Expr {
+    type: 'inExpression';
+    root: Expr;
+    target: Expr;
+}
+export interface AsNode extends Expr {
+    type: 'asExpression';
+    root: Expr;
+    conversion: string;
+}
+export interface CallNode extends Expr {
+    type: 'functionCall';
+    root: Expr;
+    args: Expr[];
+}
+export interface AttributeAccessNode extends Expr {
+    type: 'attributeRefAccess';
+    root: Expr;
+    attribute: AttributeRefNode;
+}
+export interface IndexNode extends Expr {
+    type: 'arrayIndex';
+    root: Expr;
+    first: Expr;
+    second?: Expr;
+    andBefore: boolean;
+    andAfter: boolean;
+}
+export interface UnaryNode extends Expr {
+    type: 'logicalNot' | 'negativeNumber' | 'noExpression' | 'some' | 'beepExpression';
+    root: Expr;
+}
+export interface PostfixNode extends Expr {
+    type: 'timeExpression' | 'stringPostfixExpression' | 'typeCheckExpression';
+    root: Expr;
+    /** Time factor in ms, CSS unit, or type name. */
+    suffix: number | string;
+}
+export interface BinaryNode extends Expr {
+    type: 'mathOperator' | 'logicalOperator';
+    operator: string;
+    left: Expr;
+    right: Expr;
+}
+export interface ComparisonNode extends Expr {
+    type: 'comparisonOperator';
+    operator: string;
+    left: Expr;
+    right?: Expr;
+    right2?: Expr;
+    typeName?: string;
+    ignoringCase: boolean;
+}
+export interface BlockLiteralNode extends Expr {
+    type: 'blockLiteral';
+    params: string[];
+    expr: Expr;
+}
+export interface PositionalNode extends Expr {
+    type: 'positionalExpression';
+    operator: string;
+    root: Expr;
+}
+export interface RelativeNode extends Expr {
+    type: 'relativePositionalExpression';
+    operator: string;
+    thing: Expr;
+    from: Expr;
+    inElt?: Expr;
+    withinElt?: Expr;
+    wrapping: boolean;
+}
+export interface ClosestNode extends Expr {
+    type: 'closestExpr';
+    css: string;
+    parentSearch: boolean;
+    to: Expr;
+}
+export interface CollectionNode extends Expr {
+    type: 'collectionExpression';
+    operator: 'where' | 'sorted' | 'mapped' | 'split' | 'joined';
+    root: Expr;
+    operand: Expr;
+    descending?: boolean;
+}
+export type AnyExpr = SymbolNode | LiteralNode | StringNode | ArrayNode | ObjectNode | NamedArgsNode | ParenNode | IdRefNode | ClassRefNode | QueryRefNode | AttributeRefNode | StyleRefNode | StyleLiteralNode | ImplicitMeNode | PathNode | PropertyAccessNode | OfNode | PossessiveNode | InNode | AsNode | CallNode | AttributeAccessNode | IndexNode | UnaryNode | PostfixNode | BinaryNode | ComparisonNode | BlockLiteralNode | PositionalNode | RelativeNode | ClosestNode | CollectionNode;
+/** A command: its own typed fields (declared by the module that parses it) plus `run`. */
+export interface Cmd extends Node {
+    run(ctx: Ctx): MaybeP<Completion>;
+}
+export interface Feature extends Node {
+    /** `on click or keyup`, for traces. */
+    displayName?: string;
+    /** Set on the features of a `behavior`: they share that behavior's variable scope. */
+    behavior?: string;
+    install(target: unknown, source: unknown): void;
+}
+/** The optional `catch` / `finally` blocks of a handler or a function. */
+export interface Handlers {
+    errorSymbol?: string;
+    errorHandler?: Cmd[];
+    finallyHandler?: Cmd[];
+}
+export interface Program extends Node {
+    type: 'hyperscript';
+    features: Feature[];
+}

package/dist/commands/animation.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `transition`, `settle`, `start a view transition`. Follows upstream
+ * `parsetree/commands/animations.js`.
+ */
+import type { Cmd, Expr } from '../ast';
+import type { Grammar } from '../parser';
+export interface SettleNode extends Cmd {
+    type: 'settleCommand';
+    target: Expr;
+}
+/** `settle [<target>]`: wait for a running CSS transition to finish. */
+export declare function settle(g: Grammar): void;
+export interface TransitionNode extends Cmd {
+    type: 'transitionCommand';
+    properties: Expr[];
+    from: (Expr | undefined)[];
+    /** A value, or `'initial'` for what the property was before the first transition. */
+    to: (Expr | 'initial')[];
+    over?: Expr;
+    using?: Expr;
+}
+/** `transition <property> [from <value>] to <value> … [over <time> | using <css transition>]`. */
+export declare function transition(g: Grammar): void;
+export interface ViewTransitionNode extends Cmd {
+    type: 'viewTransitionCommand';
+    body: Cmd[];
+    transitionType?: string;
+}
+/**
+ * `start [a] view transition [using "<type>"] <commands> end`. The body runs as
+ * the transition's update; leaving it early (`return`, `halt`, `break`) skips
+ * the transition.
+ */
+export declare function viewTransition(g: Grammar): void;

package/dist/commands/control.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `if`, `halt`, `return`, `exit`, `throw`. Follows upstream
+ * `parsetree/commands/controlflow.js` and `basic.js`.
+ */
+import type { Cmd, Expr } from '../ast';
+import type { Grammar } from '../parser';
+export interface IfNode extends Cmd {
+    type: 'ifCommand';
+    condition: Expr;
+    trueBranch: Cmd[];
+    falseBranch?: Cmd[];
+}
+/**
+ * `if <condition> [then] <commands> [else|otherwise <commands>] [end]`.
+ * The block runs to `end` (or `else`, or the end of the script) wherever the
+ * lines break; `else if` on one line chains without needing its own `end`.
+ */
+export declare function ifCommand(g: Grammar): void;
+export interface HaltNode extends Cmd {
+    type: 'haltCommand';
+    /** `halt the event`: stop the event but keep running the handler. */
+    keepExecuting: boolean;
+    bubbling: boolean;
+    haltDefault: boolean;
+}
+export declare function halt(g: Grammar): void;
+export interface ReturnNode extends Cmd {
+    type: 'returnCommand' | 'exitCommand';
+    value?: Expr;
+}
+export declare function returnCommand(g: Grammar): void;
+export interface ThrowNode extends Cmd {
+    type: 'throwCommand';
+    value: Expr;
+}
+export declare function throwCommand(g: Grammar): void;