tslaws 0.0.0-stage → 0.3.2

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,216 @@
-# Temporary Holding Version
+# tslaws
 
-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.
+```sh
+npm i -D tslaws   # also installs the compiler for your platform (tslaws-compiler-<platform>)
+npx tslaws init
+```
+
+Laws for TypeScript, checked the way Bend 2 checks its `LAWS.bend`: a person writes the laws, an agent writes the code,
+and one command says whether the code satisfies every law and whether any code is left unchecked.
+
+```ts
+// src/math.laws.ts
+import type { int } from 'tslaws';
+import { assume } from 'tslaws';
+import { clamp, sortNumbers } from './math';
+
+export law proved clampWithinBounds(x: number, lo: number, hi: number) {
+  assume(lo <= hi);
+  const y = clamp(x, lo, hi);
+  return y >= lo && y <= hi;
+}
+
+export law sortOrders(xs: int[]) {
+  const s = sortNumbers(xs);
+  for (let i = 1; i < s.length; i++) if (s[i - 1] > s[i]) return false;
+  return true;
+}
+```
+
+`law` is syntax of the `tsc-laws` compiler (a fork of [tsc-ts](https://github.com/vercel-labs/tsc-ts)). A law is a function
+declaration the compiler type-checks like any other. It holds for an input when it returns anything but `false` and does not
+throw. `assume(cond)` skips inputs a law does not cover. Everywhere except at the start of a statement, `law` is still an
+ordinary identifier.
+
+```
+$ tslaws check
+PROVED   clampWithinBounds (src/math.laws.ts:5) [smt]
+BOUNDED  sortOrders (src/math.laws.ts:11) [smt]
+         holds within bounds: int values stay within ±2^26; arrays hold at most 4 elements; loops run at most 4 times
+FAILED   sortKeepsLength (src/math.laws.ts:17) [property]
+         returned false
+         counterexample: [[3,3]]
+         reproduce with --seed 1090953994
+UNCOVERED sub (src/math.ts) [coverage]
+         no law reaches this exported function; add a law, or a person can mark it @tslaws-exempt and accept
+```
+
+## What "checked against the laws" means
+
+Two things, both required for exit status 0:
+
+1. **Every law holds for the code.** The implementation, not a copy of it, is what runs and what is proved.
+2. **No code escapes the laws.** Every exported function or class in the covered modules is reached by a law, directly or
+   through the functions the law calls. Covered modules are the `cover` globs of `tslaws.json`
+   (`{ "cover": ["src/**/*.ts", "!src/**/*.test.ts"] }`), or, without that file, every project module the laws import.
+
+## Statuses
+
+| Status      | Meaning                                                                                                                                             |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `proved`    | Z3 shows no input makes the law return `false`, with no bound involved.                                                                             |
+| `bounded`   | Z3 shows it for every input within stated bounds: array length (`--bound`, default 4), loop iterations, recursion depth, `int` values within ±2^26. |
+| `tested`    | `fast-check` found no counterexample in `--runs` inputs (default 200); the code does not lower to the prover. Not a proof.                          |
+| `open`      | Declared `law proved …` but not proved for every input (a bounded proof does not count), or `assume` discards nearly every input. Fails the check.  |
+| `failed`    | A counterexample, shrunk to a minimal input, with the seed to reproduce it.                                                                         |
+| `uncovered` | Exported code no law reaches. Fails the check.                                                                                                      |
+| `tampered`  | A law changed, was added or removed since `tsc-laws.lock` was accepted, or a coverage exemption is not in it. Fails the check.                      |
+| `error`     | The law cannot run: not exported, a parameter has no type, no generator for a type, load failure.                                                   |
+
+`tslaws check` exits 0 only when every law is `proved`, `bounded` or `tested`, nothing is `uncovered`, the files compile, and
+the lock matches.
+
+## Inputs come from types
+
+The compiler emits declarations and `tslaws` reads each parameter's type from them, so the full type system drives input
+generation: primitives and literals, unions, enums, template literals, arrays, tuples, interfaces and type literals (optional
+properties included), index signatures, `Date`, and type parameters through their constraints. Parameters typed `number` are
+finite doubles (no NaN, no infinities). Register a generator for a type the runner cannot derive, by its name:
+
+```ts
+import { arbitrary, fc } from 'tslaws';
+arbitrary('UserId', fc.string({ minLength: 8, maxLength: 8 }));
+```
+
+## The prover
+
+`tslaws` symbolically executes the compiled JavaScript of a law, inlining the project functions it calls, and asks Z3 for an
+input that returns `false` or breaks an obligation. A model is replayed in JavaScript, and only a reproduced failure is
+reported as `failed`.
+
+- **Numbers are IEEE doubles** (SMT-LIB floating point), so rounding, overflow and `-0` are real, and `(a + b) + c ===
+  a + (b + c)` is refuted. Z3 cannot decide most double arithmetic, so those laws stay `tested`; commutative `+` and `*` are
+  normalised so `a + b === b + a` is proved.
+- **`int` is exact.** `import type { int } from 'tslaws'` marks a whole number (`number & brand`, an ordinary number at
+  runtime). Integer arithmetic carries the obligation that results stay within ±(2^53 − 1); when the full range fails only on
+  that obligation, the proof is retried with `int` values in ±2^26 and reported `bounded`. `bigint` is exact with no bound.
+- **Arrays, loops, recursion** are unrolled up to `--bound` (default 4), making the result `bounded`. Supported: `length`,
+  indexing, literals and spread, `push`, `map`, `filter`, `every`, `some`, `reduce`, `includes`, `indexOf`, `slice(n)`,
+  `concat`, `reverse`, `sort(comparator)` (a stable sorting network), `[...new Set(xs)]`, `for`, `while`, `for…of`, `break`,
+  `continue`. Mutation is allowed only on arrays no second name can reach.
+- **Strings** are unbounded SMT strings restricted to the BMP: `+`, templates, `length`, `charAt`, indexing, `slice`,
+  `substring`, `includes`, `startsWith`, `endsWith`, `indexOf`, comparisons.
+- **Records** of any of these, and `typeof`, `Math.abs/min/max/floor/ceil/trunc`, ternaries, `const`/`let`, `assume`.
+- **`forall(xs, (x, i) => cond)` and `exists(...)`** (from `tslaws`) quantify over arrays in `assume`, law results and
+  `invariant`s. The prover lowers them over the array slots, so a claim that uses them is `bounded` by `--bound`.
+
+- **Loop invariants give proofs for every number of iterations.** Put `invariant(cond)` first in a loop body (`import {
+  invariant } from 'tslaws'`; it throws at runtime when false, so property tests check it on every iteration). The prover
+  proves the invariant on entry, assumes it at the top of an arbitrary iteration, proves it again at the end, and gives the
+  code after the loop an arbitrary state where the invariant holds and the condition is false. No unrolling, so no bound:
+
+  ```ts
+  export function sumTo(n: int): int {
+    let s = 0,
+      i = 0;
+    while (i < n) {
+      invariant(0 <= i && i <= n);
+      invariant(2 * s === i * (i - 1));
+      s += i;
+      i += 1;
+    }
+    return s as int;
+  }
+  // law proved: 2 * sumTo(n) === n * (n - 1), for every n >= 0
+  ```
+
+  Invariants live in the implementation, so the agent writes them; the laws stay the person's. Restrictions: the loop may
+  change numbers, booleans and strings but only read arrays and records, and may not `return`, `break` or `continue`.
+  This is partial correctness (a loop that never ends is not flagged).
+
+Anything else leaves the law `tested`, or a `law proved` `open`, with the reason. Z3 runs in a worker thread that is terminated if a query outlives its timeout, so a hard query cannot hang the check; property tests run in a worker too, and a law that outlives `--property-timeout` (default 30000 ms) is reported `error`: the law or the code it calls may not terminate. `TSLAWS_DEBUG=1` keeps each query as an
+`.smt2` file under `.tslaws/out/smt` to replay in `z3`.
+
+## Browser laws
+
+A law file named `*.browser.laws.ts` runs in a real browser (Chrome, Edge or Chromium; `TSLAWS_BROWSER` names another
+executable). Node generates and shrinks the inputs; each one is sent to a page where the compiled law and your code run
+against a live DOM. The law may be `async`. `tslaws/browser` has `mount`, `settle`, `click`, `type` and `fire`, and works with
+any framework or none: `mount(el => render(el))` accepts whatever renders into an element and may return its unmount.
+`a11y` and `accessible` audit a mounted component with the optional `axe-core` peer dependency, and `--browser firefox|webkit` picks another engine (`npx playwright install firefox`).
+`mountComponent` with the React, Angular, DOM and custom-element adapters tests one component in isolation with props generated from its props type (function-typed props included), plus `spy`, `rendersSame` and Testing Library style queries.
+Browser laws are `tested`, never `proved`. See [docs/laws.md](../../docs/laws.md#browser-laws).
+
+A `*.browser.laws.ts` file that imports `tslaws/e2e` instead is an end-to-end law: it runs in Node and drives your whole running app through a real browser (`page()`, `open`, `newPage`, `route`, `settle`, `accessible`). Configure `e2e.server` in `tslaws.json` and the runner starts and stops your dev server. See [End-to-end laws](../../docs/laws.md#end-to-end-laws).
+
+- **Frameworks:** `tslaws.json` `compilerOptions` (`jsx`, `jsxFactory`, `jsxFragmentFactory`, `jsxImportSource`, `experimentalDecorators`,
+  `emitDecoratorMetadata`, `useDefineForClassFields`, `lib`, `types`, `strict`, ...) and `.tsx` sources let React, Angular and any DOM
+  library be tested. See [docs/laws.md](../../docs/laws.md#frameworks).
+- **Stateful laws:** a law over `ops: Op[]` (a union type) can use `runModel` or `runModelAsync` to apply the operations to the
+  real thing and to a simple model and compare them after every step. Failing sequences shrink to the shortest one. See
+  [docs/laws.md](../../docs/laws.md#stateful-laws).
+
+## Dashboard
+
+`tslaws ui [files...] [--port N] [--no-open]` serves a local dashboard (127.0.0.1 only): a tree of files and laws,
+live progress, a live view of the browser page during browser laws, status filters, search, a report with a copyable reproduce command, the law's source, and live reruns on save.
+Laws are timed (the five slowest are listed), the last 20 runs show as a row of coloured squares, laws that flip between passing and failing are marked `flaky`, and any single law can be rerun.
+See [docs/laws.md](../../docs/laws.md#the-dashboard).
+
+`tslaws mutate [files...] [--max N] [--seed N] [--json]` mutation-tests the laws: it mutates the covered code, re-runs the laws against each mutant, and lists the survivors no law caught. It handles `.tsx`/`.jsx` and projects with a lock, and takes the run flags of `check`. See [docs/laws.md](../../docs/laws.md#mutation-testing).
+
+- **Settings:** `tslaws.json` `runs`, `bound`, `proofTimeoutMs` and `propertyTimeoutMs` set the run defaults; a command line flag beats them. See [docs/laws.md](../../docs/laws.md#settings).
+
+## Agents cannot move the goalposts
+
+`tsc-laws.lock` holds a hash of every law declaration and the list of coverage exemptions. A change, an added law, a removed
+law or a new `@tslaws-exempt` fails the check until a person runs `tslaws accept`, which refuses to run without a terminal,
+under `CI`, or with `TSLAWS_AGENT` set. Agents propose laws in `*.proposed.laws.ts` and try them with `tslaws check
+--proposed` (no lock, no coverage gate); a person moves them into a `*.laws.ts` file and accepts.
+
+`hooks/claude-hook.mjs` is a Claude Code hook that blocks `git commit` and sends an agent back to work when the check fails;
+`hooks/claude-settings.example.json` wires it up and `hooks/AGENTS.snippet.md` tells the agent the rules.
+
+## Commands
+
+```
+tslaws init [--force]
+tslaws accept [files...]
+tslaws check [files...] [--json] [--summary] [--watch] [--runs N] [--seed N] [--no-prove] [--bound N]
+             [--proof-timeout MS] [--property-timeout MS] [--proposed] [--compiler PATH]
+```
+
+- `init` scaffolds `tslaws.json`, the `.tslaws` ignore entry, the agent rules in `AGENTS.md`, the Claude Code hook in
+  `.claude/settings.json`, and a starter law if none exists. It never writes the lock; a person then runs `accept`.
+- `accept` records the laws and the `@tslaws-exempt` functions in `tsc-laws.lock`. It refuses to run without a terminal,
+  under `CI`, or with `TSLAWS_AGENT` set.
+- `check` exits 0 only when every law is `proved`, `bounded` or `tested`, nothing is `uncovered`, the files compile and the
+  lock matches. `--json` adds a `hint` to each result, the concrete next action for an agent. `--summary` prints only the
+  results that do not pass, plus the totals. `--watch` re-runs on every `.ts` change.
+- `check --reporter text|json|junit|github` picks the output: `junit` is JUnit XML for CI test reports, `github` prints workflow
+  annotations and appends a table to `GITHUB_STEP_SUMMARY`. See "CI reporters" in `docs/laws.md`.
+
+- `tslaws mcp` serves `tslaws_check`, `tslaws_check_proposed`, `tslaws_explain` and `tslaws_propose` over MCP (stdio) for
+  agents; it cannot accept laws or touch the lock. `tslaws promote` is the person's step that moves proposed laws into the
+  accepted file. See [docs/laws.md](../../docs/laws.md#agent-integration-mcp).
+- Counterexamples are kept in `.tslaws/regressions` (committable) and replayed before the random search, so a fixed bug cannot
+  return unnoticed. `check --no-regressions` skips the corpus; `tslaws regressions [list|clear]` shows or deletes it.
+
+Without files, every `*.laws.ts` under the current directory is used. The compiler is `--compiler`, `TSC_LAWS_BIN`, or
+`tsc-laws` on `PATH`; it finds its lib files through `TSC_TS_LIB_DIR`, or the TypeScript 7 libs scriptc installs in
+`node_modules/@scriptc/*`.
+
+See [docs/laws.md](../../docs/laws.md) for the language, how it compares with Bend 2, and the limits.
+
+## Build and test
+
+```
+npm ci
+npm run fetch:upstream && npm run build:native:dev -w tsc-ts   # needs clang (and zig on Windows)
+npm run build -w tslaws
+TSC_LAWS_BIN=packages/tsc-ts/dist/tsc npm test -w tslaws
+TSC_TS_BIN=packages/tsc-ts/dist/tsc node --test packages/tsc-ts/tests/laws.test.mjs
+```
+
+`tsc-ts --laws-manifest <files>` lists the laws of files as JSON (name, parameters, line, declaration text, and the problems
+that stop a law running); `tslaws` uses it for the lock and for reporting.

package/bin/tslaws.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { main } from '../dist/cli.js';
+
+// Z3's worker threads would keep the process alive.
+process.exit(await main(process.argv.slice(2)));

package/dist/adapters/angular.d.ts

@@ -0,0 +1,42 @@
+import type { Adapter } from '../component.ts';
+/** The part of Angular's `ApplicationRef` the adapter uses. */
+export interface AngularAppRefLike {
+    injector: unknown;
+    attachView(view: any): void;
+    tick(): void;
+    whenStable?(): Promise<unknown>;
+    destroy(): void;
+}
+/** The part of Angular's `ComponentRef` the adapter uses. */
+export interface AngularComponentRefLike {
+    setInput(name: string, value: unknown): void;
+    hostView: unknown;
+}
+/**
+ * The functions to pass, all from Angular itself:
+ *
+ * ```ts
+ * import { createComponent, provideZonelessChangeDetection } from '@angular/core';
+ * import { createApplication } from '@angular/platform-browser';
+ * angularAdapter({ createApplication, createComponent, provideZonelessChangeDetection });
+ * ```
+ *
+ * Without `provideZonelessChangeDetection` the application needs zone.js (import it in the law's module).
+ */
+export interface AngularFunctions {
+    /** `createApplication` from `@angular/platform-browser`. */
+    createApplication(options?: any): Promise<AngularAppRefLike>;
+    /** `createComponent` from `@angular/core`. */
+    createComponent(component: any, options: any): AngularComponentRefLike;
+    /** `provideZonelessChangeDetection` from `@angular/core`; when given it is added to the application's providers. */
+    provideZonelessChangeDetection?(): unknown;
+    /** Replaces `ref.setInput(name, value)`, for example to also assign outputs. */
+    setInput?(ref: AngularComponentRefLike, name: string, value: unknown): void;
+    /** Extra providers for the application. */
+    providers?: unknown[];
+}
+/**
+ * Renders a standalone Angular component. Props are set with `ref.setInput`; a rerender sets them again and runs change
+ * detection; unmount destroys the application.
+ */
+export declare function angularAdapter<P extends object = any>(angular: AngularFunctions): Adapter<unknown, P>;

package/dist/adapters/angular.js

@@ -0,0 +1,40 @@
+/**
+ * Renders a standalone Angular component. Props are set with `ref.setInput`; a rerender sets them again and runs change
+ * detection; unmount destroys the application.
+ */
+// oxlint-disable-next-line typescript/no-explicit-any
+export function angularAdapter(angular) {
+    return {
+        async render(container, component, props) {
+            const providers = [...(angular.providers ?? [])];
+            if (angular.provideZonelessChangeDetection !== undefined)
+                providers.push(angular.provideZonelessChangeDetection());
+            const app = await angular.createApplication({ providers });
+            const host = document.createElement('div');
+            container.appendChild(host);
+            const ref = angular.createComponent(component, { environmentInjector: app.injector, hostElement: host });
+            const set = (next) => {
+                for (const [name, value] of Object.entries(next)) {
+                    if (angular.setInput !== undefined)
+                        angular.setInput(ref, name, value);
+                    else
+                        ref.setInput(name, value);
+                }
+            };
+            const detect = async () => {
+                app.tick();
+                await app.whenStable?.();
+            };
+            set(props);
+            app.attachView(ref.hostView);
+            await detect();
+            return {
+                update: async (next) => {
+                    set(next);
+                    await detect();
+                },
+                unmount: () => app.destroy(),
+            };
+        },
+    };
+}

package/dist/adapters/dom.d.ts

@@ -0,0 +1,5 @@
+import type { Adapter } from '../component.ts';
+/** A vanilla component: a function from props to a node or markup. */
+export type DomComponent<P = any> = (props: P) => Node | string;
+/** Renders a `(props) => Node | string` function into the container; a rerender replaces the content. */
+export declare const domAdapter: Adapter<DomComponent, any>;

package/dist/adapters/dom.js

@@ -0,0 +1,17 @@
+function fill(container, content) {
+    if (typeof content === 'string')
+        container.innerHTML = content;
+    else
+        container.replaceChildren(content);
+}
+/** Renders a `(props) => Node | string` function into the container; a rerender replaces the content. */
+// oxlint-disable-next-line typescript/no-explicit-any
+export const domAdapter = {
+    render(container, component, props) {
+        fill(container, component(props));
+        return {
+            update: (next) => fill(container, component(next)),
+            unmount: () => container.replaceChildren(),
+        };
+    },
+};

package/dist/adapters/element.d.ts

@@ -0,0 +1,10 @@
+import type { Adapter } from '../component.ts';
+export interface ElementAdapterOptions {
+    /** Also set each string, number or boolean prop as an attribute (default: properties only). */
+    attributes?: boolean;
+}
+/**
+ * Renders a custom element: props are assigned as properties (and optionally attributes). The `component` argument may
+ * be the element's class, defined under `tagName` when it is not yet, or `undefined` when it is already registered.
+ */
+export declare function elementAdapter<P extends object = any>(tagName: string, options?: ElementAdapterOptions): Adapter<CustomElementConstructor | undefined, P>;

package/dist/adapters/element.js

@@ -0,0 +1,28 @@
+/**
+ * Renders a custom element: props are assigned as properties (and optionally attributes). The `component` argument may
+ * be the element's class, defined under `tagName` when it is not yet, or `undefined` when it is already registered.
+ */
+// oxlint-disable-next-line typescript/no-explicit-any
+export function elementAdapter(tagName, options = {}) {
+    const assign = (el, props) => {
+        for (const [key, value] of Object.entries(props)) {
+            el[key] = value;
+            if (options.attributes && ['string', 'number', 'boolean'].includes(typeof value)) {
+                if (value === false)
+                    el.removeAttribute(key);
+                else
+                    el.setAttribute(key, value === true ? '' : String(value));
+            }
+        }
+    };
+    return {
+        render(container, component, props) {
+            if (component !== undefined && customElements.get(tagName) === undefined)
+                customElements.define(tagName, component);
+            const el = document.createElement(tagName);
+            container.appendChild(el);
+            assign(el, props);
+            return { update: (next) => assign(el, next), unmount: () => el.remove() };
+        },
+    };
+}

package/dist/adapters/react.d.ts

@@ -0,0 +1,24 @@
+import type { Adapter } from '../component.ts';
+/** The part of React's `createRoot` result the adapter uses. */
+export interface ReactRootLike {
+    render(node: unknown): void;
+    unmount(): void;
+}
+/**
+ * The functions to pass, all from React itself:
+ *
+ * ```ts
+ * import { createElement } from 'react';
+ * import { createRoot } from 'react-dom/client';
+ * import { flushSync } from 'react-dom';
+ * reactAdapter({ createRoot, createElement, flushSync });
+ * ```
+ */
+export interface ReactFunctions {
+    createRoot(container: any): ReactRootLike;
+    createElement(type: any, props: any): unknown;
+    /** When given, renders are committed synchronously. */
+    flushSync?(callback: () => void): void;
+}
+/** Renders a React component with `createRoot`; a rerender calls `root.render`, unmount calls `root.unmount`. */
+export declare function reactAdapter<P extends object = any>(react: ReactFunctions): Adapter<unknown, P>;

package/dist/adapters/react.js

@@ -0,0 +1,15 @@
+/** Renders a React component with `createRoot`; a rerender calls `root.render`, unmount calls `root.unmount`. */
+// oxlint-disable-next-line typescript/no-explicit-any
+export function reactAdapter(react) {
+    const sync = (work) => (react.flushSync !== undefined ? react.flushSync(work) : work());
+    return {
+        render(container, component, props) {
+            const root = react.createRoot(container);
+            sync(() => root.render(react.createElement(component, props)));
+            return {
+                update: (next) => sync(() => root.render(react.createElement(component, next))),
+                unmount: () => sync(() => root.unmount()),
+            };
+        },
+    };
+}