@blotch/angular-lynx-testing-library 0.0.0-stage → 22.2.1

package/README.md

@@ -1,3 +1,367 @@
-# Temporary Holding Version
+# @blotch/angular-lynx-testing-library
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Testing utilities for [AngularLynx](https://github.com/Blotch-Smart-Frames/AngularLynx) apps. Renders Angular standalone components through the Lynx PAPI pipeline into a JSDOM tree, then exposes the result via [@testing-library/dom](https://testing-library.com/docs/dom-testing-library/intro) queries.
+
+## Installation
+
+```sh
+npm install --save-dev @blotch/angular-lynx-testing-library \
+  @lynx-js/testing-environment \
+  @testing-library/dom \
+  @testing-library/jest-dom \
+  vitest jsdom
+```
+
+## Setup
+
+Add a `vitest.config.ts` to your project:
+
+```ts
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+import path from 'node:path';
+
+export default defineConfig({
+  define: {
+    __DEV__: JSON.stringify(true),
+    __MAIN_THREAD__: JSON.stringify(true),
+  },
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    setupFiles: ['@blotch/angular-lynx-testing-library/setup'],
+  },
+});
+```
+
+The setup file:
+
+- Enables Angular JIT compilation (`@angular/compiler`)
+- Installs `LynxTestingEnv` on the jsdom window
+- Switches to the Lynx main thread (where PAPI functions live)
+- Polyfills PAPI functions the testing environment doesn't implement (`__GetParent`, `__QuerySelector`, etc.)
+- Installs `@testing-library/jest-dom` matchers
+
+## API
+
+### `render(component, options?)`
+
+Bootstraps a standalone Angular component and returns a JSDOM container with `@testing-library/dom` queries bound to it.
+
+```ts
+import { render } from '@blotch/angular-lynx-testing-library';
+
+const { container, getByText, queryByRole } = await render(MyComponent);
+```
+
+`render` is **async** — it `await`s Angular's `bootstrapApplication`. The initial change detection cycle runs before the promise resolves, so the container is ready to query immediately.
+
+**Options:**
+
+| Option      | Type                                   | Description                                                           |
+| ----------- | -------------------------------------- | --------------------------------------------------------------------- |
+| `providers` | `(Provider \| EnvironmentProviders)[]` | Additional providers injected into the app (services, tokens, mocks). |
+
+`provideZonelessChangeDetection()` and `provideRenderer()` are always included — you do not need to provide them.
+
+**Return value:**
+
+| Property     | Type         | Description                                                                                                 |
+| ------------ | ------------ | ----------------------------------------------------------------------------------------------------------- |
+| `container`  | `Element`    | The JSDOM `<page>` root element. All rendered children are descendants.                                     |
+| `unmount`    | `() => void` | Destroys the Angular app.                                                                                   |
+| `...queries` | —            | All `@testing-library/dom` queries bound to `container` (`getByText`, `queryByRole`, `findByTestId`, etc.). |
+
+### `cleanup()`
+
+Destroys the current Angular app and resets the Lynx environment. Called automatically after each test — you only need this for manual control.
+
+```ts
+import { cleanup } from '@blotch/angular-lynx-testing-library';
+
+afterEach(cleanup);
+```
+
+Set `ATL_SKIP_AUTO_CLEANUP=true` to disable auto-cleanup.
+
+### `waitForUpdate()`
+
+Waits for Angular's zoneless change detection scheduler to flush pending reactive updates, then forces a synchronous CD cycle.
+
+```ts
+import { waitForUpdate } from '@blotch/angular-lynx-testing-library';
+
+const count = signal(0);
+count.set(1);
+await waitForUpdate();
+// DOM now reflects count = 1
+```
+
+Call this after any signal mutation that happens outside an event handler (e.g. direct `.set()` in test code).
+
+### `fireEvent`
+
+Dispatches Lynx events on JSDOM elements. Use the named helpers for standard Lynx events:
+
+```ts
+import { fireEvent } from '@blotch/angular-lynx-testing-library';
+
+fireEvent.tap(element);
+fireEvent.input(element, { value: 'hello' });
+fireEvent.scroll(element, { scrollTop: 100 });
+```
+
+Named helpers dispatch a DOM event with the key `"bindEvent:<name>"` (e.g. `"bindEvent:tap"`), which matches the listener registered by `__AddEvent` when Angular processes a `(bindtap)` template binding.
+
+To dispatch a raw DOM event directly:
+
+```ts
+fireEvent(element, new Event('bindEvent:tap'));
+```
+
+**Available named helpers:**
+
+`tap` · `longtap` · `touchstart` · `touchmove` · `touchcancel` · `touchend` · `longpress` · `scroll` · `scrollend` · `focus` · `blur` · `input` · `confirm` · `layoutchange` · `transitionend` · `animationend`
+
+### `eventMap`
+
+The full Lynx event registry. Each entry has a `defaultInit` object (currently empty for all events, but present for forward-compatibility).
+
+```ts
+import { eventMap } from '@blotch/angular-lynx-testing-library';
+
+console.log(Object.keys(eventMap));
+// ['tap', 'longtap', 'touchstart', ...]
+```
+
+### Re-exports from `@testing-library/dom`
+
+`screen` · `within` · `getQueriesForElement`
+
+## Usage
+
+### Rendering a component
+
+```ts
+import { Component } from '@angular/core';
+import { render } from '@blotch/angular-lynx-testing-library';
+
+@Component({
+  selector: 'greeting',
+  template: `<text>Hello, {{ name }}!</text>`,
+})
+class GreetingComponent {
+  name = 'Lynx';
+}
+
+it('renders the greeting', async () => {
+  const { container } = await render(GreetingComponent);
+  expect(container.querySelector('text')!.textContent).toBe('Hello, Lynx!');
+});
+```
+
+### Injecting providers
+
+```ts
+import { InjectionToken, inject } from '@angular/core';
+import { render } from '@blotch/angular-lynx-testing-library';
+
+const GREETING = new InjectionToken<string>('GREETING');
+
+@Component({
+  selector: 'test-greeting',
+  template: `<text>{{ greeting() }}</text>`,
+})
+class GreetingComponent {
+  greeting = inject(GREETING);
+}
+
+it('uses the injected value', async () => {
+  const { container } = await render(GreetingComponent, {
+    providers: [{ provide: GREETING, useValue: 'Hola' }],
+  });
+  expect(container.querySelector('text')!.textContent).toBe('Hola');
+});
+```
+
+### Reactive signals
+
+Define the signal outside the component so both the component and the test can access it:
+
+```ts
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { render, waitForUpdate } from '@blotch/angular-lynx-testing-library';
+
+const count = signal(0);
+
+@Component({
+  selector: 'test-counter',
+  template: `<text>{{ count() }}</text>`,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+class CounterComponent {
+  count = count;
+}
+
+it('updates when the signal changes', async () => {
+  const { container } = await render(CounterComponent);
+  expect(container.querySelector('text')!.textContent).toBe('0');
+
+  count.set(42);
+  await waitForUpdate();
+
+  expect(container.querySelector('text')!.textContent).toBe('42');
+});
+```
+
+### Handling events
+
+AngularLynx event bindings use Lynx prefixes: `(bindtap)`, `(catchtap)`, `(bindinput)`, etc.
+
+```ts
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import {
+  render,
+  fireEvent,
+  waitForUpdate,
+} from '@blotch/angular-lynx-testing-library';
+
+@Component({
+  selector: 'test-button',
+  template: `
+    <view (bindtap)="increment()">
+      <text>{{ count() }}</text>
+    </view>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+class ButtonComponent {
+  count = signal(0);
+  increment() {
+    this.count.update((n) => n + 1);
+  }
+}
+
+it('increments on tap', async () => {
+  const { container } = await render(ButtonComponent);
+
+  fireEvent.tap(container.querySelector('view')!);
+  await waitForUpdate();
+
+  expect(container.querySelector('text')!.textContent).toBe('1');
+});
+```
+
+### Control flow — `@if`
+
+```ts
+it('shows content conditionally', async () => {
+  const visible = signal(true);
+
+  @Component({
+    selector: 'test-if',
+    template: `@if (visible()) {
+      <text>Hello</text>
+    }`,
+    changeDetection: ChangeDetectionStrategy.OnPush,
+  })
+  class IfComponent {
+    visible = visible;
+  }
+
+  const { container } = await render(IfComponent);
+  expect(container.querySelector('text')).not.toBeNull();
+
+  visible.set(false);
+  await waitForUpdate();
+  expect(container.querySelector('text')).toBeNull();
+});
+```
+
+### Control flow — `@for`
+
+```ts
+it('renders a dynamic list', async () => {
+  const items = signal(['A', 'B', 'C']);
+
+  @Component({
+    selector: 'test-for',
+    template: `@for (item of items(); track item) {
+      <text>{{ item }}</text>
+    }`,
+    changeDetection: ChangeDetectionStrategy.OnPush,
+  })
+  class ListComponent {
+    items = items;
+  }
+
+  const { container } = await render(ListComponent);
+  expect(container.querySelectorAll('text').length).toBe(3);
+
+  items.set(['A', 'B', 'C', 'D']);
+  await waitForUpdate();
+  expect(container.querySelectorAll('text').length).toBe(4);
+});
+```
+
+## Architecture notes
+
+### Single-thread model
+
+AngularLynx runs **entirely on the Lynx main thread** (`__MAIN_THREAD__ = true`). This differs from React Lynx and Vue Lynx, which split rendering across two threads:
+
+| Library         | Thread model                                                     |
+| --------------- | ---------------------------------------------------------------- |
+| React Lynx      | Dual: background thread runs React, main thread applies PAPI ops |
+| Vue Lynx        | Dual: background thread runs Vue, main thread applies PAPI ops   |
+| **AngularLynx** | **Single: Angular renderer calls PAPI directly on main thread**  |
+
+In tests, this means there is no thread switching — `__MAIN_THREAD__` stays `true` throughout, and PAPI functions (`__CreatePage`, `__CreateView`, etc.) are always available.
+
+### The render pipeline
+
+```
+render(Component)
+  └─ bootstrapApplication(Component, {
+       provideZonelessChangeDetection(),
+       provideRenderer(),
+       ...providers
+     })
+       └─ LynxDocument.createRootElement()
+            └─ __CreatePage()  →  <page> appended to document.body
+       └─ Angular renders component tree
+            └─ __CreateView / __CreateText / …  →  JSDOM children
+       └─ LynxRendererFactory2.end()
+            └─ __FlushElementTree()  (no-op in tests)
+  └─ appRef.tick()  →  force synchronous CD
+  └─ return { container: elementTree.root, ...queries }
+```
+
+### Event dispatch
+
+AngularLynx registers event handlers via `__AddEvent(element, eventType, eventName, { type: 'worklet', value: callback })`. The testing environment stores this as a DOM event listener under the key `"${eventType}:${eventName}"` (e.g. `"bindEvent:tap"`).
+
+`fireEvent.tap(el)` dispatches a `"bindEvent:tap"` DOM event, which triggers the listener. The listener calls `runWorklet(callback, [event])` which invokes the Angular handler directly on the main thread.
+
+Template binding → PAPI registration → DOM listener key:
+
+| Template       | Listener key       |
+| -------------- | ------------------ |
+| `(bindtap)`    | `bindEvent:tap`    |
+| `(catchtap)`   | `catchEvent:tap`   |
+| `(bindinput)`  | `bindEvent:input`  |
+| `(bindscroll)` | `bindEvent:scroll` |
+
+## Comparison with React/Vue Lynx testing libraries
+
+| Feature                 | React Lynx              | Vue Lynx          | AngularLynx             |
+| ----------------------- | ----------------------- | ----------------- | ----------------------- |
+| `render()` return       | Sync                    | Sync              | **Async**               |
+| Thread model            | Dual (BG+MT)            | Dual (BG+MT)      | **Main only**           |
+| Auto-cleanup env var    | `PTL_SKIP_AUTO_CLEANUP` | —                 | `ATL_SKIP_AUTO_CLEANUP` |
+| `renderHook()`          | ✓                       | —                 | —                       |
+| Snapshot serializer     | ✓ (RefProxy)            | —                 | —                       |
+| Vitest plugin           | ✓                       | —                 | —                       |
+| Named fireEvent helpers | 30+                     | 16                | 16                      |
+| Thread-aware fireEvent  | ✓                       | ✓                 | — (single thread)       |
+| Async state helper      | `waitSchedule()`        | `waitForUpdate()` | `waitForUpdate()`       |

package/dist/fire-event.d.ts

@@ -0,0 +1,128 @@
+/**
+ * fireEvent — dispatches Lynx events through the dual-thread pipeline.
+ *
+ * Lynx events are registered via __AddEvent with a key of "bindEvent:<name>"
+ * (e.g. "bindEvent:tap"). The event handler stored on the element calls
+ * lynxCoreInject.tt.publishEvent(handlerSign, eventData) which routes the
+ * event to the background thread (not used by AngularLynx, which runs on
+ * the main thread).
+ *
+ * For AngularLynx, the (event) bindings in templates are wired by
+ * LynxRenderer.listen() which calls __AddEvent internally. The DOM event
+ * dispatched here triggers that listener directly on the main thread.
+ */
+export declare const eventMap: {
+    tap: {
+        defaultInit: {};
+    };
+    longtap: {
+        defaultInit: {};
+    };
+    touchstart: {
+        defaultInit: {};
+    };
+    touchmove: {
+        defaultInit: {};
+    };
+    touchcancel: {
+        defaultInit: {};
+    };
+    touchend: {
+        defaultInit: {};
+    };
+    longpress: {
+        defaultInit: {};
+    };
+    keydown: {
+        defaultInit: {};
+    };
+    keyup: {
+        defaultInit: {};
+    };
+    mousedown: {
+        defaultInit: {};
+    };
+    mouseup: {
+        defaultInit: {};
+    };
+    mousemove: {
+        defaultInit: {};
+    };
+    mouseclick: {
+        defaultInit: {};
+    };
+    mousedblclick: {
+        defaultInit: {};
+    };
+    mouselongpress: {
+        defaultInit: {};
+    };
+    wheel: {
+        defaultInit: {};
+    };
+    scroll: {
+        defaultInit: {};
+    };
+    scrollend: {
+        defaultInit: {};
+    };
+    scrolltoupper: {
+        defaultInit: {};
+    };
+    scrolltolower: {
+        defaultInit: {};
+    };
+    contentsizechanged: {
+        defaultInit: {};
+    };
+    scrolltoupperedge: {
+        defaultInit: {};
+    };
+    scrolltoloweredge: {
+        defaultInit: {};
+    };
+    scrolltonormalstate: {
+        defaultInit: {};
+    };
+    focus: {
+        defaultInit: {};
+    };
+    blur: {
+        defaultInit: {};
+    };
+    input: {
+        defaultInit: {};
+    };
+    confirm: {
+        defaultInit: {};
+    };
+    layoutchange: {
+        defaultInit: {};
+    };
+    bgload: {
+        defaultInit: {};
+    };
+    bgerror: {
+        defaultInit: {};
+    };
+    transitionstart: {
+        defaultInit: {};
+    };
+    transitionend: {
+        defaultInit: {};
+    };
+    transitioncancel: {
+        defaultInit: {};
+    };
+    animationend: {
+        defaultInit: {};
+    };
+};
+type EventName = keyof typeof eventMap;
+type EventHandler = (elem: Element, init?: Record<string, unknown>) => boolean;
+type FireEvent = ((elem: Element, event: Event) => boolean) & {
+    [K in EventName]: EventHandler;
+};
+export declare const fireEvent: FireEvent;
+export {};
+//# sourceMappingURL=fire-event.d.ts.map

package/dist/fire-event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fire-event.d.ts","sourceRoot":"","sources":["../src/fire-event.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2CpB,CAAC;AAEF,KAAK,SAAS,GAAG,MAAM,OAAO,QAAQ,CAAC;AACvC,KAAK,YAAY,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;AAC/E,KAAK,SAAS,GAAG,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,GAAG;KAC3D,CAAC,IAAI,SAAS,GAAG,YAAY;CAC/B,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,SAET,CAAC"}

package/dist/fire-event.js

@@ -0,0 +1,79 @@
+/**
+ * fireEvent — dispatches Lynx events through the dual-thread pipeline.
+ *
+ * Lynx events are registered via __AddEvent with a key of "bindEvent:<name>"
+ * (e.g. "bindEvent:tap"). The event handler stored on the element calls
+ * lynxCoreInject.tt.publishEvent(handlerSign, eventData) which routes the
+ * event to the background thread (not used by AngularLynx, which runs on
+ * the main thread).
+ *
+ * For AngularLynx, the (event) bindings in templates are wired by
+ * LynxRenderer.listen() which calls __AddEvent internally. The DOM event
+ * dispatched here triggers that listener directly on the main thread.
+ */
+import { createEvent, fireEvent as domFireEvent } from '@testing-library/dom';
+const EVENT_INIT_KEYS = new Set(['bubbles', 'cancelable', 'composed']);
+export const eventMap = {
+    // Touch / gesture
+    tap: { defaultInit: {} },
+    longtap: { defaultInit: {} },
+    touchstart: { defaultInit: {} },
+    touchmove: { defaultInit: {} },
+    touchcancel: { defaultInit: {} },
+    touchend: { defaultInit: {} },
+    longpress: { defaultInit: {} },
+    // Keyboard
+    keydown: { defaultInit: {} },
+    keyup: { defaultInit: {} },
+    // Mouse
+    mousedown: { defaultInit: {} },
+    mouseup: { defaultInit: {} },
+    mousemove: { defaultInit: {} },
+    mouseclick: { defaultInit: {} },
+    mousedblclick: { defaultInit: {} },
+    mouselongpress: { defaultInit: {} },
+    wheel: { defaultInit: {} },
+    // Scroll / viewport
+    scroll: { defaultInit: {} },
+    scrollend: { defaultInit: {} },
+    scrolltoupper: { defaultInit: {} },
+    scrolltolower: { defaultInit: {} },
+    contentsizechanged: { defaultInit: {} },
+    scrolltoupperedge: { defaultInit: {} },
+    scrolltoloweredge: { defaultInit: {} },
+    scrolltonormalstate: { defaultInit: {} },
+    // Form / focus
+    focus: { defaultInit: {} },
+    blur: { defaultInit: {} },
+    input: { defaultInit: {} },
+    confirm: { defaultInit: {} },
+    // Layout / image
+    layoutchange: { defaultInit: {} },
+    bgload: { defaultInit: {} },
+    bgerror: { defaultInit: {} },
+    // Transition / animation
+    transitionstart: { defaultInit: {} },
+    transitionend: { defaultInit: {} },
+    transitioncancel: { defaultInit: {} },
+    animationend: { defaultInit: {} },
+};
+export const fireEvent = ((elem, event) => {
+    return domFireEvent(elem, event);
+});
+for (const key of Object.keys(eventMap)) {
+    fireEvent[key] = (elem, init) => {
+        const eventType = init?.['eventType'] ?? 'bindEvent';
+        const eventInit = {
+            eventType,
+            eventName: key,
+            ...eventMap[key].defaultInit,
+            ...init,
+        };
+        const event = createEvent(`${eventType}:${key}`, elem, eventInit);
+        // Assign Lynx-specific custom properties (eventType, eventName, etc.).
+        // Standard EventInit keys are read-only on constructed events so we skip them.
+        const customProps = Object.fromEntries(Object.entries(eventInit).filter(([k]) => !EVENT_INIT_KEYS.has(k)));
+        Object.assign(event, customProps);
+        return domFireEvent(elem, event);
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { render, cleanup, waitForUpdate } from './render.js';
+export type { RenderOptions, RenderResult } from './render.js';
+export type { ComponentRef } from '@angular/core';
+export { fireEvent, eventMap } from './fire-event.js';
+export { screen, within, getQueriesForElement } from '@testing-library/dom';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC7D,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC/D,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,29 @@
+export { render, cleanup, waitForUpdate } from './render.js';
+export { fireEvent, eventMap } from './fire-event.js';
+export { screen, within, getQueriesForElement } from '@testing-library/dom';
+import { cleanup } from './render.js';
+/**
+ * Auto-cleanup after each test (matches @testing-library/react convention).
+ * Set ATL_SKIP_AUTO_CLEANUP=true to opt out. Uses the global afterEach so this
+ * works with vitest, jest, and jasmine.
+ */
+const registerAutoCleanup = () => {
+    const _afterEach = globalThis.afterEach;
+    if (typeof _afterEach === 'function') {
+        _afterEach(() => {
+            cleanup();
+            globalThis.lynxTestingEnv?.reset();
+        });
+    }
+};
+// `process` is absent in non-Node runners (e.g. a browser). That guard cannot
+// execute under Node/Vitest — and faking a process-less global crashes Angular's
+// import (it reads process.platform) — so it is excluded from coverage. The
+// Node path (the opt-out env check) is fully tested.
+/* v8 ignore next 2 -- @preserve non-Node guard: unreachable + untestable under Vitest */
+if (typeof process === 'undefined') {
+    registerAutoCleanup();
+}
+else if (process.env['ATL_SKIP_AUTO_CLEANUP'] !== 'true') {
+    registerAutoCleanup();
+}

package/dist/render.d.ts

@@ -0,0 +1,65 @@
+/**
+ * render() — bootstraps an Angular standalone component through the full
+ * Lynx dual-thread pipeline and returns a container element (JSDOM) with
+ * @testing-library/dom queries.
+ *
+ * Pipeline:
+ *   1. switchToMainThread() → PAPI globals (__CreatePage, __CreateView, …) active
+ *   2. bootstrapApplication(component, { provideRenderer(), … })
+ *      → LynxDocument.createRootElement() → __CreatePage → JSDOM <page> in body
+ *      → Angular renders tree → __CreateView/Text/… → JSDOM children
+ *      → LynxRendererFactory2.end() → __FlushElementTree() (no-op in tests)
+ *   3. appRef.tick() forces synchronous CD so all signal-driven updates land
+ *   4. Return JSDOM container + @testing-library/dom queries
+ */
+import { type ComponentRef, type EnvironmentProviders, type Provider, type Type } from '@angular/core';
+import { type BoundFunctions, type Queries, queries as domQueries } from '@testing-library/dom';
+export type RenderOptions<Q extends Queries = typeof domQueries> = {
+    providers?: (Provider | EnvironmentProviders)[];
+    /**
+     * Custom query helpers to merge with the standard `@testing-library/dom` queries.
+     * Each helper receives the container as its first argument when bound.
+     * Workaround if omitted: call `getQueriesForElement(container, customQueries)` directly.
+     */
+    queries?: Q;
+};
+export type RenderResult<Q extends Queries = typeof domQueries> = {
+    /**
+     * The JSDOM root element (page element) containing all rendered children.
+     */
+    container: Element;
+    /**
+     * Unmount the current Angular app.
+     */
+    unmount: () => void;
+    /**
+     * Re-render a (possibly different) component into the same body position,
+     * replacing the running app without manually calling cleanup() first.
+     */
+    rerender: <R extends Queries = Q>(component: Type<unknown>, options?: RenderOptions<R>) => Promise<RenderResult<R>>;
+    /**
+     * Returns a DocumentFragment snapshot of the container — use for snapshot testing.
+     */
+    asFragment: () => DocumentFragment;
+    /**
+     * The Angular ComponentRef for the bootstrapped root component.
+     *
+     * Key uses:
+     *   - `componentRef.injector.get(Token)` — retrieve a service provided to the app.
+     *   - `componentRef.instance.someSignal.set(v)` — drive writable signal state directly.
+     *
+     * Note: `componentRef.setInput()` requires the full AOT pipeline to register
+     * signal inputs (input()) or @Input() decorators in component metadata. In the
+     * Vitest JIT environment this metadata is not available, so the recommended
+     * pattern is to expose writable signals on the component instance instead.
+     */
+    componentRef: ComponentRef<unknown>;
+} & BoundFunctions<typeof domQueries> & BoundFunctions<Q>;
+export declare const cleanup: () => void;
+export declare const render: <Q extends Queries = typeof domQueries>(rootComponent: Type<unknown>, options?: RenderOptions<Q>) => Promise<RenderResult<Q>>;
+/**
+ * Wait for all pending Angular reactive updates to flush through the pipeline.
+ * Call this after programmatic signal changes that happen outside event handlers.
+ */
+export declare const waitForUpdate: () => Promise<void>;
+//# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,QAAQ,EAEb,KAAK,IAAI,EACV,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,OAAO,EACZ,OAAO,IAAI,UAAU,EAEtB,MAAM,sBAAsB,CAAC;AAG9B,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,UAAU,IAAI;IACjE,SAAS,CAAC,EAAE,CAAC,QAAQ,GAAG,oBAAoB,CAAC,EAAE,CAAC;IAChD;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,UAAU,IAAI;IAChE;;OAEG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB;;OAEG;IACH,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB;;;OAGG;IACH,QAAQ,EAAE,CAAC,CAAC,SAAS,OAAO,GAAG,CAAC,EAC9B,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,EACxB,OAAO,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,KACvB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9B;;OAEG;IACH,UAAU,EAAE,MAAM,gBAAgB,CAAC;IACnC;;;;;;;;;;;OAWG;IACH,YAAY,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC;CACrC,GAAG,cAAc,CAAC,OAAO,UAAU,CAAC,GACnC,cAAc,CAAC,CAAC,CAAC,CAAC;AAIpB,eAAO,MAAM,OAAO,QAAO,IAM1B,CAAC;AAEF,eAAO,MAAM,MAAM,GAAU,CAAC,SAAS,OAAO,GAAG,OAAO,UAAU,EAChE,eAAe,IAAI,CAAC,OAAO,CAAC,EAC5B,UAAS,aAAa,CAAC,CAAC,CAA0B,KACjD,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAkDzB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,QAAa,OAAO,CAAC,IAAI,CAKlD,CAAC"}

package/dist/render.js

@@ -0,0 +1,74 @@
+/**
+ * render() — bootstraps an Angular standalone component through the full
+ * Lynx dual-thread pipeline and returns a container element (JSDOM) with
+ * @testing-library/dom queries.
+ *
+ * Pipeline:
+ *   1. switchToMainThread() → PAPI globals (__CreatePage, __CreateView, …) active
+ *   2. bootstrapApplication(component, { provideRenderer(), … })
+ *      → LynxDocument.createRootElement() → __CreatePage → JSDOM <page> in body
+ *      → Angular renders tree → __CreateView/Text/… → JSDOM children
+ *      → LynxRendererFactory2.end() → __FlushElementTree() (no-op in tests)
+ *   3. appRef.tick() forces synchronous CD so all signal-driven updates land
+ *   4. Return JSDOM container + @testing-library/dom queries
+ */
+import { provideZonelessChangeDetection, } from '@angular/core';
+import { bootstrapApplication } from '@angular/platform-browser';
+import { queries as domQueries, getQueriesForElement, } from '@testing-library/dom';
+import { provideRenderer } from '@blotch/angular-lynx';
+let currentAppRef = null;
+export const cleanup = () => {
+    if (currentAppRef) {
+        const ref = currentAppRef;
+        currentAppRef = null;
+        ref.destroy();
+    }
+};
+export const render = async (rootComponent, options = {}) => {
+    cleanup();
+    // Switch to main thread so PAPI functions (__CreatePage, __CreateView, …)
+    // are available as globals. LynxDocument requires them to create elements.
+    const env = globalThis.lynxTestingEnv;
+    env.switchToMainThread();
+    // Clear JSDOM body so previous render's elements are gone.
+    const doc = globalThis.document;
+    doc.body.innerHTML = '';
+    // Bootstrap Angular. LynxDocument.createRootElement() runs during bootstrap,
+    // calling __CreatePage which appends the <page> element to document.body.
+    const appRef = await bootstrapApplication(rootComponent, {
+        providers: [
+            provideZonelessChangeDetection(),
+            provideRenderer(),
+            ...(options.providers ?? []),
+        ],
+    });
+    currentAppRef = appRef;
+    // Force a synchronous CD cycle so signal-initialized state is reflected in
+    // the DOM before we return. bootstrapApplication already triggers one CD,
+    // but zoneless scheduling may defer follow-up updates to a microtask.
+    appRef.tick();
+    // elementTree.root is the JSDOM <page> element created by __CreatePage.
+    const container = globalThis.elementTree.root;
+    const componentRef = appRef.components[0];
+    return {
+        container,
+        unmount: () => cleanup(),
+        rerender: (newComponent, newOptions) => render(newComponent, newOptions ?? {}),
+        asFragment: () => document.createRange().createContextualFragment(container.outerHTML),
+        componentRef,
+        ...getQueriesForElement(container, {
+            ...domQueries,
+            ...options.queries,
+        }),
+    };
+};
+/**
+ * Wait for all pending Angular reactive updates to flush through the pipeline.
+ * Call this after programmatic signal changes that happen outside event handlers.
+ */
+export const waitForUpdate = async () => {
+    // Yield to the microtask/macrotask queue so zoneless CD scheduler can enqueue.
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    // Then force synchronous CD to apply any queued updates to the DOM.
+    currentAppRef?.tick();
+};

package/dist/setup.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Vitest setup file for AngularLynx testing library.
+ *
+ * Runs in the jsdom environment and:
+ *   1. Creates LynxTestingEnv wrapping the existing jsdom window.
+ *   2. Polyfills PAPI functions that the testing-environment doesn't implement
+ *      but the AngularLynx runtime requires.
+ *   3. Switches to main thread so PAPI globals are active before Angular bootstraps.
+ *
+ * AngularLynx runs on the main thread (__MAIN_THREAD__ = true):
+ *   - LynxDocument uses PAPI functions (__CreatePage, __CreateView, …)
+ *   - LynxRendererFactory2.end() calls __FlushElementTree (no-op in tests)
+ *
+ * Why we polyfill: the @lynx-js/testing-environment's ElementPAPI covers the
+ * core PAPI surface used by React/Vue Lynx, but AngularLynx calls additional
+ * PAPI functions (__GetParent, __NextElement, __QuerySelector*, etc.) that the
+ * testing environment does not implement. Since testing-environment elements ARE
+ * real JSDOM HTMLElements, we can implement these with native DOM methods.
+ */
+import '@angular/compiler';
+import '@testing-library/jest-dom/vitest';
+//# sourceMappingURL=setup.d.ts.map

package/dist/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,mBAAmB,CAAC;AAC3B,OAAO,kCAAkC,CAAC"}

package/dist/setup.js

@@ -0,0 +1,143 @@
+/**
+ * Vitest setup file for AngularLynx testing library.
+ *
+ * Runs in the jsdom environment and:
+ *   1. Creates LynxTestingEnv wrapping the existing jsdom window.
+ *   2. Polyfills PAPI functions that the testing-environment doesn't implement
+ *      but the AngularLynx runtime requires.
+ *   3. Switches to main thread so PAPI globals are active before Angular bootstraps.
+ *
+ * AngularLynx runs on the main thread (__MAIN_THREAD__ = true):
+ *   - LynxDocument uses PAPI functions (__CreatePage, __CreateView, …)
+ *   - LynxRendererFactory2.end() calls __FlushElementTree (no-op in tests)
+ *
+ * Why we polyfill: the @lynx-js/testing-environment's ElementPAPI covers the
+ * core PAPI surface used by React/Vue Lynx, but AngularLynx calls additional
+ * PAPI functions (__GetParent, __NextElement, __QuerySelector*, etc.) that the
+ * testing environment does not implement. Since testing-environment elements ARE
+ * real JSDOM HTMLElements, we can implement these with native DOM methods.
+ */
+// Must come before @angular/platform-browser to enable JIT compilation
+// in tests (TypeScript source is not pre-compiled with the Angular compiler).
+import '@angular/compiler';
+import '@testing-library/jest-dom/vitest';
+import { LynxTestingEnv } from '@lynx-js/testing-environment';
+// ─── CSS fetch intercept ─────────────────────────────────────────────────────
+/**
+ * Angular JIT calls fetch('./component.css') to load external styleUrls.
+ * jsdom has no base URL, so relative URLs fail. Return empty 200 for .css fetches.
+ */
+const _originalFetch = globalThis.fetch;
+globalThis.fetch = (url, ...args) => {
+    if (typeof url === 'string' && url.endsWith('.css')) {
+        return Promise.resolve(new Response('', { status: 200 }));
+    }
+    return _originalFetch(url, ...args);
+};
+// ─── Element.prototype.animate stub ──────────────────────────────────────────
+// jsdom does not implement the Web Animations API. Define a no-op stub so
+// vi.spyOn(Element.prototype, 'animate') can mock it in individual tests.
+if (typeof Element.prototype.animate !== 'function') {
+    Element.prototype.animate = () => ({ cancel: () => { }, finished: Promise.resolve() });
+}
+// ─── Install LynxTestingEnv ──────────────────────────────────────────────────
+const lynxTestingEnv = new LynxTestingEnv({ window: globalThis.window });
+globalThis.lynxTestingEnv = lynxTestingEnv;
+// Expose Node so @testing-library/dom detects element types correctly.
+globalThis.Node = globalThis.window.Node;
+// ─── Switch to main thread ───────────────────────────────────────────────────
+// PAPI globals (__CreatePage, __CreateView, elementTree, …) are active on the
+// main thread. AngularLynx must run here because LynxDocument uses these APIs.
+lynxTestingEnv.switchToMainThread();
+// ─── runWorklet polyfill ─────────────────────────────────────────────────────
+// __AddEvent in the testing environment calls runWorklet(handler, [event]) when
+// an event handler is registered as type:'worklet'. AngularLynx registers all
+// event handlers this way (see LynxElement.addEventListener). runWorklet simply
+// invokes the callback — same as the polyfill in runtime.ts for the real device.
+globalThis.runWorklet = (value, params) => {
+    if (typeof value === 'function') {
+        value(...params);
+    }
+};
+// ─── Missing PAPI polyfills ──────────────────────────────────────────────────
+// The testing-environment's ElementPAPI uses real JSDOM HTMLElements as the
+// native element representation. So DOM traversal methods work natively on them.
+// We polyfill the subset of PAPI that AngularLynx uses but testing-environment
+// does not implement.
+/**
+ * Returns the parent of a JSDOM element (equivalent to element.parentNode).
+ */
+globalThis.__GetParent = (e) => e.parentElement ?? e.parentNode;
+/**
+ * Returns the next sibling element.
+ */
+globalThis.__NextElement = (e) => e.nextElementSibling ?? e.nextSibling;
+/**
+ * querySelector on a JSDOM element.
+ */
+globalThis.__QuerySelector = (e, selector) => e.querySelector(selector);
+/**
+ * querySelectorAll on a JSDOM element — returns an array.
+ */
+globalThis.__QuerySelectorAll = (e, selector) => Array.from(e.querySelectorAll(selector));
+/**
+ * Returns the eventMap stored on the element by __AddEvent.
+ * LynxElement.addEventListener uses this to identify listeners to remove.
+ */
+globalThis.__GetEvents = (e) => e.eventMap ?? {};
+/**
+ * Replaces the eventMap on the element. Used by the removeEventListener path.
+ */
+globalThis.__SetEvents = (e, events) => {
+    e.eventMap = Object.fromEntries(events.map((ev) => [ev.type + ':' + ev.name, ev.jsFunction]));
+};
+// Element creators that @lynx-js/testing-environment doesn't implement.
+// They fall back to __CreateElement (also a JSDOM element with a custom tag).
+for (const tag of ['block', 'for', 'frame', 'if']) {
+    globalThis[`__Create${tag.charAt(0).toUpperCase() + tag.slice(1)}`] =
+        (parentComponentUniqueId) => globalThis.__CreateElement(tag, parentComponentUniqueId);
+}
+/**
+ * __CreateNonElement creates an invisible placeholder (comment anchor).
+ */
+globalThis.__CreateNonElement = () => globalThis.__CreateElement('non-element', 0);
+/**
+ * Class manipulation helpers.
+ */
+globalThis.__AddClass = (e, cls) => e.classList.add(cls);
+// Must return an array — LynxElement.removeClass() calls .filter() on the result.
+globalThis.__GetClasses = (e) => Array.from(e.classList);
+globalThis.__SetClasses = (e, classes) => {
+    e.className = classes;
+};
+/**
+ * Returns the direct element children of a JSDOM element.
+ * __CreateRawText returns a DOM TextNode (not HTMLElement), so text content
+ * inside <text> elements is excluded here — matching Lynx PAPI semantics where
+ * __GetChildren returns Lynx elements only, not raw-text nodes. This means
+ * LynxElement.remove()'s child-parking loop becomes a no-op for <text>
+ * elements, letting __RemoveElement proceed and correctly detach the element.
+ */
+globalThis.__GetChildren = (e) => Array.from(e.children);
+/**
+ * __SetConfig is called during bootstrap to pass Lynx config; no-op in tests.
+ */
+globalThis.__SetConfig = () => { };
+/**
+ * Invokes a native UI method by name (e.g. the `setValue` UIMethod that Lynx
+ * inputs/textareas require for programmatic text updates — see
+ * LynxElement.invoke() in the runtime). LynxElement.invoke() always passes an
+ * empty result callback, so a no-op that still calls back (matching the real
+ * host's async {code, data} contract) is sufficient here.
+ */
+globalThis.__InvokeUIMethod = (_element, _methodName, _params, callback) => {
+    callback?.({ code: 0 });
+};
+// ─── After reset ─────────────────────────────────────────────────────────────
+// lynxTestingEnv.reset() re-injects globals from scratch. Re-establish main
+// thread context and restore our polyfills afterwards.
+globalThis.onResetLynxTestingEnv = () => {
+    lynxTestingEnv.switchToMainThread();
+    // runWorklet is a polyfill on globalThis; it survives reset since we set it
+    // on the outer globalThis (not the per-thread globalThis).
+};

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@blotch/angular-lynx-testing-library",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "22.2.1",
+  "description": "Testing utilities for AngularLynx apps",
+  "homepage": "https://github.com/Blotch-Smart-Frames/AngularLynx#readme",
+  "bugs": {
+    "url": "https://github.com/Blotch-Smart-Frames/AngularLynx/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Blotch-Smart-Frames/AngularLynx.git",
+    "directory": "packages/testing-library"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./setup": {
+      "types": "./dist/setup.d.ts",
+      "import": "./dist/setup.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:ci:coverage": "vitest run --coverage",
+    "test:ui": "vitest --ui --coverage.enabled=true",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint --fix .",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check .",
+    "cspell": "cspell .",
+    "publish:local": "yalc publish --push"
+  },
+  "dependencies": {
+    "@lynx-js/testing-environment": "^0.3.4",
+    "@testing-library/dom": "^10.4.1"
+  },
+  "devDependencies": {
+    "@angular/compiler": "^22.2.1",
+    "@angular/core": "^22.2.1",
+    "@angular/platform-browser": "^22.2.1",
+    "@blotch/angular-lynx": "*",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@types/node": "^22.0.0",
+    "jsdom": "^25.0.0",
+    "typescript": "~6.0.0"
+  },
+  "peerDependencies": {
+    "@angular/compiler": "^22.2.0",
+    "@angular/core": "^22.2.0",
+    "@angular/platform-browser": "^22.2.0",
+    "@blotch/angular-lynx": "^22.2.0"
+  }
+}