@hyperfixi/reactivity 2.4.0

package/src/integration.test.ts

@@ -0,0 +1,585 @@
+/**
+ * End-to-end integration — parse + installPlugin + execute round-trip.
+ *
+ * Uses the `registry.snapshot()` / `registry.restore(baseline)` pattern to
+ * isolate plugin installations from other tests in the process.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { Runtime, hyperscript } from '@hyperfixi/core';
+import { parse } from '@hyperfixi/core';
+import { getParserExtensionRegistry, installPlugin } from '@hyperfixi/core';
+import type { ExecutionContext } from '@hyperfixi/core/src/types/core';
+import { reactivityPlugin, reactive } from './index';
+
+function createContext(me: HTMLElement): ExecutionContext {
+  return {
+    me,
+    it: null,
+    you: null,
+    result: null,
+    locals: new Map(),
+    globals: new Map(),
+    variables: new Map(),
+    events: new Map(),
+  } as unknown as ExecutionContext;
+}
+
+/** Drain microtasks + the setTimeout queue so reactive effects settle. */
+async function settle(): Promise<void> {
+  for (let i = 0; i < 20; i++) await Promise.resolve();
+  await new Promise<void>(resolve => setTimeout(resolve, 0));
+  for (let i = 0; i < 20; i++) await Promise.resolve();
+}
+
+describe('@hyperfixi/reactivity — integration', () => {
+  const registry = getParserExtensionRegistry();
+  let baseline: ReturnType<typeof registry.snapshot>;
+  let runtime: Runtime;
+
+  beforeEach(() => {
+    baseline = registry.snapshot();
+    runtime = new Runtime();
+    installPlugin(runtime, reactivityPlugin);
+  });
+
+  afterEach(() => {
+    registry.restore(baseline);
+  });
+
+  describe('install idempotency', () => {
+    it('installing the plugin twice does not duplicate global-write hooks', async () => {
+      // Install a second time — should be a no-op thanks to the hasFeature guard.
+      installPlugin(runtime, reactivityPlugin);
+
+      const el = document.createElement('div');
+      document.body.appendChild(el);
+      const ctx = createContext(el);
+      ctx.globals.set('count', 0);
+
+      let runs = 0;
+      const r = parse('live\n  set $mirror to $count\nend');
+      expect(r.success).toBe(true);
+      // Wrap the live body in our own counter via a wrapping effect.
+      const stop = reactive.createEffect(
+        () => {
+          reactive.trackGlobal('count');
+          return ctx.globals.get('count');
+        },
+        () => {
+          runs++;
+        },
+        el
+      );
+      await runtime.execute(r.node!, ctx);
+      await settle();
+
+      const baselineRuns = runs;
+      ctx.globals.set('count', 1);
+      reactive.notifyGlobal('count');
+      await settle();
+      // Exactly one additional run despite the duplicate install attempt.
+      expect(runs).toBe(baselineRuns + 1);
+
+      stop();
+      document.body.removeChild(el);
+    });
+  });
+
+  describe('live', () => {
+    it('re-runs the body when a tracked global changes', async () => {
+      // The live body sets $total from $price; changing $price should re-run
+      // the body and update $total.
+      const el = document.createElement('div');
+      document.body.appendChild(el);
+      const ctx = createContext(el);
+      ctx.globals.set('price', 10);
+      ctx.globals.set('total', 0);
+
+      const r = parse('live\n  set $total to $price\nend');
+      expect(r.success).toBe(true);
+      await runtime.execute(r.node!, ctx);
+      await settle();
+
+      // Initial run set total = 10.
+      expect(ctx.globals.get('total')).toBe(10);
+
+      // Change price — live should re-run and update total.
+      ctx.globals.set('price', 42);
+      reactive.notifyGlobal('price'); // emulate the set path's notify hook
+      await settle();
+      expect(ctx.globals.get('total')).toBe(42);
+
+      document.body.removeChild(el);
+    });
+  });
+
+  describe('when ... changes', () => {
+    it('runs the body when the watched expression changes', async () => {
+      const el = document.createElement('div');
+      el.id = 'target';
+      document.body.appendChild(el);
+      const ctx = createContext(el);
+      ctx.globals.set('message', 'hello');
+
+      // when $message changes, put it into me → updates textContent.
+      const r = parse('when $message changes\n  put it into me\nend');
+      expect(r.success).toBe(true);
+      await runtime.execute(r.node!, ctx);
+      await settle();
+
+      // Initial: textContent should equal 'hello' because handler fires on init.
+      expect(el.textContent).toBe('hello');
+
+      ctx.globals.set('message', 'world');
+      reactive.notifyGlobal('message');
+      await settle();
+      expect(el.textContent).toBe('world');
+
+      document.body.removeChild(el);
+    });
+  });
+
+  describe('bind', () => {
+    it('two-way binds a global var to an input value', async () => {
+      const input = document.createElement('input');
+      input.type = 'text';
+      input.value = 'initial';
+      document.body.appendChild(input);
+      const ctx = createContext(input);
+      ctx.globals.set('greeting', 'pending');
+
+      const r = parse('bind $greeting to me');
+      expect(r.success).toBe(true);
+      await runtime.execute(r.node!, ctx);
+      await settle();
+
+      // After init, one side wins; expect the var to sync with the DOM value
+      // (DOM → var direction runs first).
+      expect(ctx.globals.get('greeting')).toBe('initial');
+
+      // Programmatic var write → DOM updated.
+      ctx.globals.set('greeting', 'updated');
+      reactive.notifyGlobal('greeting');
+      await settle();
+      expect(input.value).toBe('updated');
+
+      // User input → var updated.
+      input.value = 'typed';
+      input.dispatchEvent(new Event('input'));
+      await settle();
+      expect(ctx.globals.get('greeting')).toBe('typed');
+
+      document.body.removeChild(input);
+    });
+
+    it('two-way binds a local var (`:name`) to an input value', async () => {
+      const input = document.createElement('input');
+      input.type = 'text';
+      input.value = 'initial';
+      document.body.appendChild(input);
+      const ctx = createContext(input);
+      ctx.locals.set('greeting', 'pending');
+
+      const r = parse('bind :greeting to me');
+      expect(r.success).toBe(true);
+      await runtime.execute(r.node!, ctx);
+      await settle();
+
+      // DOM → var on init (DOM wins).
+      expect(ctx.locals.get('greeting')).toBe('initial');
+
+      // User input updates the local via DOM→var effect.
+      input.value = 'typed';
+      input.dispatchEvent(new Event('input'));
+      await settle();
+      expect(ctx.locals.get('greeting')).toBe('typed');
+
+      document.body.removeChild(input);
+    });
+
+    it('auto-detects checkbox → checked', async () => {
+      const cb = document.createElement('input');
+      cb.type = 'checkbox';
+      cb.checked = false;
+      document.body.appendChild(cb);
+      const ctx = createContext(cb);
+      ctx.globals.set('isOn', true);
+
+      const r = parse('bind $isOn to me');
+      expect(r.success).toBe(true);
+      await runtime.execute(r.node!, ctx);
+      await settle();
+
+      // DOM → var on init (DOM wins).
+      expect(ctx.globals.get('isOn')).toBe(false);
+
+      // var → DOM
+      ctx.globals.set('isOn', true);
+      reactive.notifyGlobal('isOn');
+      await settle();
+      expect(cb.checked).toBe(true);
+
+      document.body.removeChild(cb);
+    });
+
+    it("explicit property via possessive (`me's value`) on a text input", async () => {
+      const input = document.createElement('input');
+      input.type = 'text';
+      input.value = 'initial';
+      document.body.appendChild(input);
+      const ctx = createContext(input);
+      ctx.globals.set('greeting', 'pending');
+
+      const r = parse("bind $greeting to me's value");
+      expect(r.success).toBe(true);
+      await runtime.execute(r.node!, ctx);
+      await settle();
+
+      // DOM → var on init.
+      expect(ctx.globals.get('greeting')).toBe('initial');
+
+      // var → DOM.
+      ctx.globals.set('greeting', 'updated');
+      reactive.notifyGlobal('greeting');
+      await settle();
+      expect(input.value).toBe('updated');
+
+      // DOM → var on user input (form-like element, listener still active).
+      input.value = 'typed';
+      input.dispatchEvent(new Event('input'));
+      await settle();
+      expect(ctx.globals.get('greeting')).toBe('typed');
+
+      document.body.removeChild(input);
+    });
+
+    it('explicit property via member access (`me.value`) on a text input', async () => {
+      const input = document.createElement('input');
+      input.type = 'text';
+      input.value = 'hello';
+      document.body.appendChild(input);
+      const ctx = createContext(input);
+      ctx.globals.set('greeting', 'pending');
+
+      const r = parse('bind $greeting to me.value');
+      expect(r.success).toBe(true);
+      await runtime.execute(r.node!, ctx);
+      await settle();
+
+      expect(ctx.globals.get('greeting')).toBe('hello');
+
+      ctx.globals.set('greeting', 'changed');
+      reactive.notifyGlobal('greeting');
+      await settle();
+      expect(input.value).toBe('changed');
+
+      document.body.removeChild(input);
+    });
+
+    it('explicit property targets a non-default property (color input value)', async () => {
+      // A color input's default `value` is the same as auto-detect, but this
+      // test pins the explicit-property path against a specific property name
+      // rather than relying on type-based auto-detection.
+      const picker = document.createElement('input');
+      picker.type = 'color';
+      picker.value = '#ff0000';
+      document.body.appendChild(picker);
+      const ctx = createContext(picker);
+      ctx.globals.set('color', '#000000');
+
+      const r = parse("bind $color to me's value");
+      expect(r.success).toBe(true);
+      await runtime.execute(r.node!, ctx);
+      await settle();
+
+      // DOM → var on init.
+      expect(ctx.globals.get('color')).toBe('#ff0000');
+
+      // var → DOM (explicit property name; auto-detect would have picked the
+      // same string — but the code path here goes through the unwrap branch).
+      ctx.globals.set('color', '#00ff00');
+      reactive.notifyGlobal('color');
+      await settle();
+      expect(picker.value).toBe('#00ff00');
+
+      document.body.removeChild(picker);
+    });
+
+    it('var → DOM works for non-form properties; DOM → var is skipped', async () => {
+      // Binding a div's textContent: var→DOM should propagate; the listener
+      // for DOM→var isn't installed because input/change don't fire on divs.
+      const div = document.createElement('div');
+      div.textContent = 'initial';
+      document.body.appendChild(div);
+      const ctx = createContext(div);
+      ctx.globals.set('text', 'override');
+
+      const r = parse("bind $text to me's textContent");
+      expect(r.success).toBe(true);
+      await runtime.execute(r.node!, ctx);
+      await settle();
+
+      // No DOM→var sync, so the var keeps its pre-bind value.
+      expect(ctx.globals.get('text')).toBe('override');
+
+      // var → DOM fires on the initial run because var !== DOM.
+      expect(div.textContent).toBe('override');
+
+      // var → DOM continues to fire on subsequent writes.
+      ctx.globals.set('text', 'updated');
+      reactive.notifyGlobal('text');
+      await settle();
+      expect(div.textContent).toBe('updated');
+
+      document.body.removeChild(div);
+    });
+
+    it('throws with a multi-level hint for chained property access on RHS', async () => {
+      const div = document.createElement('div');
+      document.body.appendChild(div);
+      const ctx = createContext(div);
+      // `me.style.backgroundColor` — chained .style.backgroundColor.
+      const r = parse('bind $color to me.style.backgroundColor');
+      expect(r.success).toBe(true);
+      await expect(runtime.execute(r.node!, ctx)).rejects.toThrow(/multi-level property access/);
+      document.body.removeChild(div);
+    });
+
+    it('throws with type+snippet hint when RHS does not resolve to an element', async () => {
+      const div = document.createElement('div');
+      document.body.appendChild(div);
+      const ctx = createContext(div);
+      // String literal on RHS isn't a var-ref, so we reach the element check
+      // with a non-element value and surface the new diagnostic.
+      const r = parse('bind $value to "just-a-string"');
+      expect(r.success).toBe(true);
+      await expect(runtime.execute(r.node!, ctx)).rejects.toThrow(
+        /did not resolve to an element \(got string "just-a-string"\)\. If you meant to write to a property/
+      );
+      document.body.removeChild(div);
+    });
+  });
+
+  describe('^name DOM-scoped vars', () => {
+    it('writes a caret var via `set ^X to Y`', async () => {
+      const host = document.createElement('div');
+      document.body.appendChild(host);
+      const ctx = createContext(host);
+
+      const r = parse('set ^count to 5');
+      expect(r.success).toBe(true);
+      await runtime.execute(r.node!, ctx);
+      await settle();
+      expect(reactive.readCaret(host, 'count')).toBe(5);
+
+      document.body.removeChild(host);
+    });
+
+    it('mutates a caret var via `increment ^X`', async () => {
+      const host = document.createElement('div');
+      document.body.appendChild(host);
+      const ctx = createContext(host);
+
+      reactive.writeCaret(host, 'count', 10, host);
+
+      const r = parse('increment ^count');
+      expect(r.success).toBe(true);
+      await runtime.execute(r.node!, ctx);
+      await settle();
+      expect(reactive.readCaret(host, 'count')).toBe(11);
+
+      await runtime.execute(r.node!, ctx);
+      await settle();
+      expect(reactive.readCaret(host, 'count')).toBe(12);
+
+      document.body.removeChild(host);
+    });
+
+    it('hyperscript.process binds click handler that increments ^count', async () => {
+      // Tests the components-style flow: build DOM, hyperscript.process binds
+      // _= attributes, simulate click, verify ^count updated.
+      const host = document.createElement('div');
+      host.innerHTML = '<button _="on click increment ^count">+</button>';
+      document.body.appendChild(host);
+
+      reactive.writeCaret(host, 'count', 0, host);
+
+      hyperscript.process(host);
+      // Settle whatever async parsing/binding happens.
+      await settle();
+
+      const button = host.querySelector('button')!;
+      button.click();
+      await settle();
+      expect(reactive.readCaret(host, 'count')).toBe(1);
+
+      button.click();
+      await settle();
+      expect(reactive.readCaret(host, 'count')).toBe(2);
+
+      button.click();
+      await settle();
+      expect(reactive.readCaret(host, 'count')).toBe(3);
+
+      document.body.removeChild(host);
+    });
+
+    it("simulates click-counter: button increments host's ^count", async () => {
+      // Mirrors the @hyperfixi/components click-counter scenario: a button
+      // inside a host element runs `increment ^count`. The host owns ^count.
+      const host = document.createElement('div');
+      const button = document.createElement('button');
+      host.appendChild(button);
+      document.body.appendChild(host);
+
+      // Init: host owns ^count
+      const initCtx = createContext(host);
+      const initRes = parse('set ^count to 0');
+      expect(initRes.success).toBe(true);
+      await runtime.execute(initRes.node!, initCtx);
+      await settle();
+      expect(reactive.readCaret(host, 'count')).toBe(0);
+
+      // Click handler: button executes `increment ^count` with me=button
+      const clickCtx = createContext(button);
+      const clickRes = parse('increment ^count');
+      expect(clickRes.success).toBe(true);
+
+      await runtime.execute(clickRes.node!, clickCtx);
+      await settle();
+      expect(reactive.readCaret(host, 'count')).toBe(1);
+
+      await runtime.execute(clickRes.node!, clickCtx);
+      await runtime.execute(clickRes.node!, clickCtx);
+      await settle();
+      expect(reactive.readCaret(host, 'count')).toBe(3);
+
+      document.body.removeChild(host);
+    });
+
+    it('reads an inherited caret var', async () => {
+      const parent = document.createElement('div');
+      const child = document.createElement('span');
+      parent.appendChild(child);
+      document.body.appendChild(parent);
+
+      reactive.writeCaret(parent, 'theme', 'dark');
+      const ctx = createContext(child);
+
+      // Expression `^theme` reads from the parent.
+      const r = parse('set :t to ^theme');
+      expect(r.success).toBe(true);
+      await runtime.execute(r.node!, ctx);
+      await settle();
+      expect(ctx.locals.get('t')).toBe('dark');
+
+      document.body.removeChild(parent);
+    });
+
+    it('reads `^name on <target>` end-to-end via parser + runtime', async () => {
+      const a = document.createElement('div');
+      const b = document.createElement('div');
+      b.id = 'caret-target';
+      document.body.appendChild(a);
+      document.body.appendChild(b);
+
+      reactive.writeCaret(b, 'count', 99, b);
+
+      const ctx = createContext(a);
+      // me=a, but we want to read ^count from b via `on`.
+      const r = parse('set :v to ^count on #caret-target');
+      expect(r.success).toBe(true);
+      await runtime.execute(r.node!, ctx);
+      await settle();
+
+      expect(ctx.locals.get('v')).toBe(99);
+
+      document.body.removeChild(a);
+      document.body.removeChild(b);
+    });
+  });
+
+  describe('local hooks (cross-handler propagation)', () => {
+    it('a `set :foo` from elsewhere triggers an effect that read `:foo`', async () => {
+      const el = document.createElement('div');
+      document.body.appendChild(el);
+      const ctx = createContext(el);
+      ctx.locals.set('foo', 'initial');
+
+      // Effect tracking the local read via the runtime path (so localReadHook fires).
+      let lastSeen: unknown = undefined;
+      const stop = reactive.createEffect(
+        async () => await runtime.execute(parse('set :v to :foo').node!, ctx),
+        () => {
+          lastSeen = ctx.locals.get('v');
+        },
+        el
+      );
+      await settle();
+      expect(lastSeen).toBe('initial');
+
+      // Programmatic `set :foo to ...` from a SEPARATE parse+execute (same context.me).
+      // Without local hooks this would be silent; with them, the effect re-runs.
+      await runtime.execute(parse('set :foo to "updated"').node!, ctx);
+      await settle();
+      expect(lastSeen).toBe('updated');
+
+      stop();
+      document.body.removeChild(el);
+    });
+  });
+
+  describe('coverage gaps', () => {
+    it('bind effects tear down when the owning element is cleaned up', async () => {
+      const input = document.createElement('input');
+      input.type = 'text';
+      input.value = 'a';
+      document.body.appendChild(input);
+      const ctx = createContext(input);
+      ctx.globals.set('x', 'a');
+
+      const r = parse('bind $x to me');
+      expect(r.success).toBe(true);
+      await runtime.execute(r.node!, ctx);
+      await settle();
+
+      // Tear down the element via the cleanup registry.
+      runtime.cleanup(input);
+      document.body.removeChild(input);
+
+      // Programmatic var write must NOT touch the (cleaned-up) DOM. If the
+      // var→DOM effect were still alive, input.value would become 'b'.
+      ctx.globals.set('x', 'b');
+      reactive.notifyGlobal('x');
+      await settle();
+      expect(input.value).toBe('a');
+    });
+
+    it('long-lived bind survives 200 user-input events', async () => {
+      const input = document.createElement('input');
+      input.type = 'text';
+      input.value = '';
+      document.body.appendChild(input);
+      const ctx = createContext(input);
+      ctx.globals.set('x', '');
+
+      const r = parse('bind $x to me');
+      expect(r.success).toBe(true);
+      await runtime.execute(r.node!, ctx);
+      await settle();
+
+      // 200 separate user-input events. Without the cycle-counter reset (from
+      // the previous PR), the DOM→var effect would halt at lifetime trigger #101
+      // and the global would freeze.
+      for (let i = 0; i < 200; i++) {
+        input.value = `v${i}`;
+        input.dispatchEvent(new Event('input'));
+        await settle();
+      }
+      expect(ctx.globals.get('x')).toBe('v199');
+
+      document.body.removeChild(input);
+    });
+  });
+});

package/src/live.ts

@@ -0,0 +1,68 @@
+/**
+ * `live ... end` — reactive block. Body re-runs whenever any dependency read
+ * during its execution changes.
+ *
+ * Upstream syntax:
+ *   live [commandList] end
+ *
+ * Each command in the body is re-executed as a single effect. The entire
+ * body shares one effect instance; its dependency set is the union of every
+ * read performed during body execution.
+ */
+
+import type { ASTNode, ExecutionContext, FeatureParserCtx } from './types';
+import { reactive } from './signals';
+
+export interface LiveFeatureNode extends ASTNode {
+  type: 'liveFeature';
+  body: ASTNode[];
+}
+
+/**
+ * Parse `live ... end`. The `live` keyword has already been consumed by the
+ * parser dispatcher; we parse the body and expect a trailing `end`.
+ */
+export function parseLiveFeature(ctx: unknown, token: unknown): ASTNode {
+  const pctx = ctx as FeatureParserCtx;
+  const body = pctx.parseCommandListUntilEnd();
+  // parseCommandListUntilEnd stops when it sees `end` (but doesn't consume it).
+  if (!pctx.isAtEnd() && pctx.check('end')) pctx.match('end');
+  const tok = token as { start?: number; end?: number; line?: number; column?: number };
+  return {
+    type: 'liveFeature',
+    body,
+    start: tok?.start ?? 0,
+    end: pctx.getPosition().end,
+    line: tok?.line,
+    column: tok?.column,
+  } as LiveFeatureNode;
+}
+
+/**
+ * Create an evaluator bound to a runtime reference. The plugin captures
+ * `runtime` at install time and passes it in so effect re-runs can dispatch
+ * the body commands without going through module-scope state.
+ */
+export function makeEvaluateLiveFeature(runtime: {
+  execute(node: ASTNode, ctx: ExecutionContext): Promise<unknown>;
+}): (node: ASTNode, ctx: unknown) => unknown | Promise<unknown> {
+  return async function evaluateLiveFeature(node, ctx) {
+    const context = ctx as ExecutionContext;
+    const owner = (context.me as Element) ?? document.body;
+    const n = node as LiveFeatureNode;
+
+    const stop = reactive.createEffect(
+      async () => {
+        for (const cmd of n.body) {
+          await runtime.execute(cmd, context);
+        }
+      },
+      () => {
+        /* no-op — side effects happened inside the expression */
+      },
+      owner
+    );
+    context.registerCleanup?.(owner, stop, 'live-effect');
+    return undefined;
+  };
+}