@openmbee/opensysml 0.9.1 → 0.10.0

package/README.md

@@ -5,10 +5,18 @@ models over the `sysml-grpc` service, using the [Connect
 protocol](https://connectrpc.com/docs/protocol) with protobuf bodies. No native
 addon, so an install is a plain registry fetch.
 
+For a task-oriented walkthrough, see the
+[Node client guide](https://runtime.opensysml.org/clients/node/).
+
 ```bash
-npm install @openmbee/opensysml        # from npm, once the first release is published
+npm install @openmbee/opensysml
 ```
 
+A development snapshot is published every night under the `nightly` dist-tag
+(`npm install @openmbee/opensysml@nightly`), with its platform packages carrying
+that night's `sysml-grpc`; `latest` stays the stable release. See [Nightly
+snapshots](https://runtime.opensysml.org/project/nightly/).
+
 ```ts
 import { loads, connect } from "@openmbee/opensysml";
 
@@ -82,8 +90,8 @@ third a field the answer did not carry.
 `SysMLVerdict` (`holds` / `fails` / `undecided`) and `FeatureValue` (`single` /
 `many` / `error`) are unions of the same shape; every verdict arm carries a `standing` — the
 engine that answered, the strength of its evidence (`observed`, `witnessed`, `bounded`,
-`proved`) and the bounds it ran under — empty from a service without the `engines`
-capability. Integers are `bigint`, because
+`proved`) and the bounds it ran under, with `reported` and `reached` beside them —
+empty from a service without the `engines` capability. Integers are `bigint`, because
 the service's `int64` does not fit a `number` — an exact comparison against a
 scenario expectation would otherwise be a lie.
 
@@ -168,6 +176,91 @@ Two limits to plan for rather than discover:
 `fetch` transport, and asserts the allowed origin is answered on the preflight
 while another origin is not.
 
+## WebAssembly, without a service
+
+`connectWasm()` uses the same `Connection`, `Model`, values and errors over the
+combined `sysml-wasm` module. It serves `ParseFile`, `ParseSources`,
+`GetDiagnostics`, `GetSymbol`, `Evaluate`, `Instantiate`, `ExecuteAction`,
+`ExecuteState` and `GetServerInfo`. Those are the module's complete RPC surface;
+other capability-gated operations fail with `MissingCapabilityError`, and a
+direct unsupported RPC fails with `UNIMPLEMENTED`.
+The adapter uses JSON encoding; requesting protobuf encoding is refused.
+
+In Node, install the optional `@openmbee/opensysml-wasm` package at the same
+version as this client. `connectWasm()` resolves its module and matching Go
+runtime automatically and runs a worker thread by default:
+
+```bash
+npm install @openmbee/opensysml@<version> @openmbee/opensysml-wasm@<version>
+```
+
+```ts
+import { connectWasm } from "@openmbee/opensysml";
+
+await using connection = await connectWasm();
+const model = await connection.loads("package Demo { part def Car; }");
+```
+
+To use a module from another source, pass both the module and its matching Go
+runtime:
+
+```ts
+await using connection = await connectWasm({
+  wasm: "./sysml-wasm.wasm",
+  wasmExec: "/path/to/the/matching/wasm_exec.js",
+});
+const model = await connection.loads("package Demo { part def Car; }");
+```
+
+The WASM module and `wasm_exec.js` must come from compatible Go toolchains.
+The worker remains referenced while the connection is open, so `close()` or
+`await using` ends it. `thread: "inline"` runs Go on the calling thread instead;
+it is useful when a worker is unavailable, but blocks that thread during a call.
+Closing an inline connection disables its client surface; Go has no exit hook to
+stop the running module.
+A worker-mode deadline rejects the waiting call without interrupting Go, so
+later worker calls queue behind work that outlived its deadline. Inline calls
+run synchronously and cannot be interrupted while they block the JavaScript
+thread.
+
+In a browser, omit `worker` to run inline, or provide a module worker serving the
+package's `browser/wasm-worker` entry point:
+
+```ts
+import { connectWasm } from "@openmbee/opensysml/browser";
+
+const worker = new Worker("/assets/opensysml-wasm-worker.js", { type: "module" });
+await using connection = await connectWasm({
+  wasm: new URL("./sysml-wasm.wasm", import.meta.url),
+  wasmExec: new URL("./wasm_exec.js", import.meta.url),
+  worker,
+});
+```
+
+If the page loads `wasm_exec.js` itself, omit `wasmExec` to use the installed Go
+constructor.
+
+The browser worker module can be bundled from
+`@openmbee/opensysml/browser/wasm-worker`. Bundle the module and runtime from
+the npm package with:
+
+```ts
+const wasm = new URL("@openmbee/opensysml-wasm/sysml-wasm.wasm", import.meta.url);
+const wasmExec = new URL("@openmbee/opensysml-wasm/wasm_exec.js", import.meta.url);
+```
+
+Or fetch both from jsDelivr, replacing `<version>` with the matching package
+version:
+
+```text
+https://cdn.jsdelivr.net/npm/@openmbee/opensysml-wasm@<version>/sysml-wasm.wasm
+https://cdn.jsdelivr.net/npm/@openmbee/opensysml-wasm@<version>/wasm_exec.js
+```
+
+Browser callers pass those URLs as `wasm` and `wasmExec`; browser package
+resolution is not automatic. The combined module measures about 7.8 MB gzipped
+and 5.5 MB with Brotli.
+
 ## Protobuf, not JSON
 
 Bodies are protobuf by default. JSON is available (`connect({ encoding: "json" })`)
@@ -228,7 +321,8 @@ Every failure is an `OpenSysMLError`. A call the service refused is a
 `"INVALID_ARGUMENT"`, …), and the statuses worth catching by themselves have a
 subclass: `ModelNotFoundError` (the service no longer holds that hash),
 `ModelFileNotFoundError`, `InvalidRequestError`, `ServiceTimeoutError`,
-`UnsupportedOperationError`. A name the model has not got is a
+`ServiceUnavailableError` (the service was unreachable or died before
+answering), `UnsupportedOperationError`. A name the model has not got is a
 `SymbolNotFoundError`, which carries the `symbolName` it looked for and the
 `suggestions` closest to it:
 
@@ -242,6 +336,22 @@ try {
 }
 ```
 
+The wider surface adds its own:
+
+| error | what happened |
+| --- | --- |
+| `StaleServiceError` | the running service reports another version than `version` asked for |
+| `ExecutionError` | an execution the service ran failed; carries `diagnostics` |
+| `WrongKindError` | a verification or analysis named a symbol of another kind |
+| `AnalysisRunError` | an analysis run failed before it could report |
+| `ConversionError` | the service could not write the notation asked for |
+| `MigrationError` | the service could not read the SysML v1 model, so nothing of it was migrated |
+| `UnsupportedValueError` | the service sent a value this version of the client cannot decode |
+| `QueryError` | a `Query` failed in-band |
+| `DocumentQueryError` | a `runDocumentQuery` failed in-band |
+| `EditError` | an edit was refused — `failure` names which, and the subclasses (`NoEditsError`, `EditTargetError`, `InvalidEditError`, `IllegalMemberKindError`, `RenameReferencedError`, `OverlappingEditsError`, `EditResultError`, `OwnerNotFoundError`, `OwnerNotNamespaceError`, `MemberNameTakenError`, `DeleteReferencedError`, `OwnerInsideTargetError`, `MoveReferencedError`, `ReferencedElsewhereError`) catch one kind of refusal |
+| `TypeMismatchError` / `InstanceTypeError` / `FeatureValueError` | a typed view read a feature of another kind, an instance of another type, or a slot that is an error |
+
 Source that does not parse is not a failure: `load`/`loads` return a model whose
 `hasErrors` is true and whose `diagnostics` say where. Each `ModelDiagnostic` has
 `severity`, `message`, `code` and an optional location; branch on `code`
@@ -310,8 +420,10 @@ In order, and each step refuses rather than falling back to the next:
 1. **A shipped pin.** `release-digests.json`, synced from
    `client/release-digests.json` by `python3 scripts/sync-release-digests.py`
    and published in the tarball, pins the SHA-256 of every asset of a release.
-   Where it pins one, that is what the bytes must hash to, and a served
-   `.sha256` that disagrees is tampering: the download fails.
+   The release job stamps the release it publishes into the tarball's copy
+   before packing it, so a published package pins its own release. Where the
+   table pins one, that is what the bytes must hash to, and a served `.sha256`
+   that disagrees is tampering: the download fails.
 2. **The release's signed manifest.** With no pin, the client downloads
    `SHA256SUMS.txt` and its sigstore bundle `SHA256SUMS.txt.bundle`, verifies
    the bundle against the release pipeline's certificate identity (the CircleCI
@@ -361,21 +473,224 @@ install @openmbee/opensysml` must not need `buf`, Go or a network fetch of a
 plugin, and a published tarball has to contain the compiled output. CI runs
 `make proto-ts` and fails on any diff, so committed and generated cannot drift.
 
-## What v1 does not do
+## Several documents
+
+`connection.parseSources` parses several documents as one model — files the
+service reads, or inline content named for its diagnostics:
+
+```ts
+import { SourceDocument } from "@openmbee/opensysml";
+
+const model = await connection.parseSources([
+  SourceDocument.file("library.sysml"),
+  SourceDocument.inline("user.sysml", "package User { import Library::*; }"),
+]);
+model.documents;   // the names the parse gave them, in order
+model.roots;       // one root symbol per document
+```
+
+## Conversion and save
+
+`connection.convert` writes a model, a file or source out in another notation —
+`"sysml"`, `"kerml"`, `"turtle"`, `"api-json"` — and `save` writes the result to
+a path, converting when needed:
+
+```ts
+import { save } from "@openmbee/opensysml";
+
+const rdf = await connection.convert("turtle", { modelHash: model.hash });
+await save(model, "out.ttl");            // format comes from the extension
+await save(rdf, "copy.ttl");             // a Conversion writes what it holds
+```
+
+An experimental conversion emits a warning (`process.emitWarning`) rather than
+failing, and reports it through `Conversion.experimentalNotice`.
+
+## Migrating a SysML v1 model
 
-This client covers `GetServerInfo`, `ParseFile`, `GetSymbol`, `Evaluate` and
-`Instantiate` — connection, lifecycle, capability negotiation, and the five RPCs
-above. Deliberately **not** in v1, rather than half-implemented:
+A SysML v1 model — a Cameo/MagicDraw `.mdzip`, a UML XMI `.xmi` or an Eclipse
+UML2 `.uml` export — is **migrated, not converted**: a conversion is lossless,
+and a migration accounts for every v1 element as `mapped`, `approximated`,
+`unmapped` or `skipped`. `connection.convert` refuses one with an
+`InvalidRequestError` that says so and names `migrate`, whether `fromFormat` is
+`xmi`, `uml` or `mdzip` or the path's extension is; `connection.migrate` is the
+verb, and `save` writes what it answers with its image files beside it:
 
-- generated model-ergonomics types (`python -m opensysml.generate`'s equivalent);
-- the edit API (`ApplyEdits`);
-- RDF conversion (`Convert`);
-- verification helpers (`VerifyConstraint`, `VerifyRequirement`,
-  `VerifySatisfaction`);
-- `Query`, `GetDiagnostics`, `EvaluateCalc`, `RunAnalysis`, `ExecuteAction`, `ExecuteState`.
+```ts
+const migration = await connection.migrate("sysml", { path: "Model.mdzip" }, { report: true });
+console.log(migration.report.summary);            // migrated 93 element(s): 78 mapped, 12 approximated, …
+for (const entry of migration.report.byVerdict("unmapped")) {
+  console.log(`${entry.kind} ${entry.name}: ${entry.note}`);
+}
+await save(migration, "Model.sysml");             // and images/… beside it
+```
 
-`connection.rpc` is the escape hatch: it is the generated Connect client, so any
-RPC not covered here can still be called, without the ergonomic layer.
+`save` refuses, with a `RangeError` and before writing anything, a path that is
+the v1 model itself and an image that would land outside the model's directory
+or over the model, as `sysml -migrate -o` does.
+
+Inline `content` is the file's bytes (`Uint8Array`) and needs `fromFormat` to
+say which form they are; a v2 `fromFormat` is refused with a pointer at
+`convert`. The `Migration` carries the notation (or Turtle, `"ttl"`) and a
+`MigrationReport` whose `summary` and four counts always come back; `report:
+true` adds every element's `MigrationEntry` and the `text` the command's
+`-migration-report` writes, `results: true` the `-migration-results` index,
+and `layoutPath`/`layoutContent`, `imageBaseUrl` and `strict` are the other
+companion flags. Migration is experimental and warns as the RDF direction does;
+a model the service cannot read at all is a `MigrationError`.
+
+## Query and documents
+
+```ts
+const elements = await model.query({ oslc: "sysml:name = \"Wheel\"" });
+const rows = await model.runDocumentQuery("Observatory::PartsList", {
+  subject: new ElementRef("Demo::sedan"),
+});
+const markdown = await model.renderDocument("Observatory::Overview");
+```
+
+`query` also takes a structured form (`payload`/`scope`/`select`/`where`, or a
+wire `query`), never both a structured form and `oslc`. A binding value is an
+`ElementRef`, an `ObjectRef`, a primitive or a quantity; `runDocumentQuery`
+answers the typed `DocumentQueryResult` — `rows` of `DocumentValue`s, the schema
+the query declared — and `renderDocument` answers Markdown, or HTML with
+`{ form: "html" }`.
+
+## Execution and exploration
+
+```ts
+const result = await model.executeAction("Demo::Drive", {
+  inputs: { distance: 120 },
+});
+const state = await model.executeState("Demo::Ignition");
+```
+
+`executeAction` and `executeState` answer the run — `outputs`, `events`, the
+`trace` of each step — and refuse `schedule: "explore"`, because an exploration
+is not a run: `exploreAction`, `exploreState` and `exploreAnalysis` answer an
+`Exploration` (`outcomes`, `runs`, `budgetsHit`) instead. `{ schedule: "explore" }`
+is their default; any other schedule there is refused the same way. A
+`performer` names the engine a run is handed to, where the service schedules.
+
+## Verification, analysis and sweep
+
+```ts
+const verdict = await model.verifyConstraint("Demo::MassBudget", {
+  subject: "Demo::sedan",
+  question: "worst-case",
+});
+verdict.verdict.kind;                    // "holds" | "fails" | "undecided"
+await model.satisfied();                 // every asserted satisfy holds
+
+const validation = await model.validateInstance("Demo::sedan");
+const computed = await model.calc("Demo::TotalMass", { arguments: [2] });
+const analysis = await model.runAnalysis("Demo::TradeStudy", { subject: "Demo::sedan" });
+const table = await model.runSweep("Demo::TradeStudy", {
+  power: [{ kind: "int", value: 100n }, { kind: "int", value: 300n }, { kind: "int", value: 50n }],
+}, { samples: 25, seed: 7 });
+```
+
+A verification raises `WrongKindError` for a symbol of another kind and keeps a
+`fails` or `undecided` verdict as an answer rather than a failure.
+`runAnalysis` answers the run's `outputs`, `verdicts`, `instances` and
+`diagnostics` — a failed analysis still answers what it completed.
+`runSweep` takes a `Record` of `parameter → [from, to]` or `[from, to, step]`
+ranges and answers the `SweepTable` of rows, each carrying its own error when a
+run fails.
+
+## Engines
+
+```ts
+for (const engine of await connection.listEngines()) {
+  engine.name; engine.authority;           // what it answers: verification, analysis, ...
+}
+```
+
+`engine` selects one on the calls above (`verifyConstraint`, `validateInstance`,
+`calc`, `runAnalysis`, `verifySatisfaction`), and `explainVerdict` /
+`explainStanding` say how a verdict was reached — the engine and the strength of
+its evidence (`observed`, `witnessed`, `bounded`, `proved`).
+
+## Authoring
+
+`model.edit()` starts a batch of source-preserving edits, applied atomically:
+
+```ts
+const editor = model.edit();
+editor.addItemDef("Car", "Demo");
+editor.rename("Demo::Wheel", "Tire");
+const applied = await editor.apply();
+applied.documents;      // every document the batch rewrote, by parse name
+```
+
+Every `add*` of the Python client is here — `addPackage` … `addRequirement`,
+`addCalcDef`, `addParameter`, `addPerformAction`, `addStateAction`,
+`addAssertConstraint`, `addTransition`, `addImport`, `addDocumentation`,
+`addMetadata`, `addVerify`, `addObjective`, `addSatisfy`, plus `setValue`,
+`rename`, `delete(target, { cascade })` and `move(target, owner)` — and
+`Body` builds guarded then/else and nested if/while/for blocks for action
+bodies. Edits are validated eagerly (a `RangeError` or `TypeError` at the
+`add*` call, not at `apply()`) and capability-gated per operation and per
+field. `connection.applyEdits(modelHash, operations)` is the low-level form,
+taking wire `EditOperation` messages.
+
+An edit the service refuses raises the typed error for the failure —
+`EditTargetError`, `RenameReferencedError`, `DeleteReferencedError`,
+`MemberNameTakenError`, `OwnerNotFoundError`, `OverlappingEditsError` and the
+rest of the `EditError` family, each carrying `failure`, `diagnostics`,
+`referringElements` and structured `referrers`.
+
+## Service version and required capabilities
+
+`connect()` negotiates what the service must be, beside what it must advertise:
+
+```ts
+await using connection = await connect({
+  version: "0.9",
+  requireCapabilities: [CAPABILITY_VERIFY, CAPABILITY_DOCUMENT_QUERY],
+});
+```
+
+A running service that reports another version is a `StaleServiceError`
+naming the required and reported versions — the remedy is to point at a service
+of the required version, or accept what is running by omitting `version`
+(`$OPENSYSML_GRPC_VERSION` is the environment form). A service missing a required
+capability is likewise refused at connect, rather than at the first gated call.
+
+## Typed module generation
+
+`opensysml-generate` writes a TypeScript module of typed views over a model's
+definitions — `Vehicle`, `SportsCar` — so `model.instantiate` reads as
+`vehicle.wheels`, with each feature's declared type, instead of
+`tree.get("wheels")`:
+
+```bash
+npx opensysml-generate model.sysml -o src/vehicle_types.ts
+npx opensysml-generate model.sysml --check -o src/vehicle_types.ts   # fails when stale
+```
+
+```ts
+import { Vehicle } from "./vehicle_types.js";
+const vehicle = Vehicle.fromInstance(await model.instantiate("Demo::Car"), tree.byId);
+vehicle.wheels;                    // readonly Instance[], typed
+vehicle.mass;                      // Quantity | undefined, as declared
+```
+
+A class `extends` its first base, declares the features of the rest as getters
+so every inherited feature stays reachable, and `fromInstance` accepts
+subtypes; a feature of another kind raises `TypeMismatchError` or
+`InstanceTypeError`. The module is stamped with a hash of the source text, and
+`--check` regenerates on drift. Generated code imports only from
+`@openmbee/opensysml` and runs under the browser entry point too.
+
+## What this client does not do
+
+- `save` writes a single document's content; a multi-document `EditResult`
+  (`applied`/`documents` rather than one `content`) is written by the caller,
+  per `EditedDocument`.
+- `connection.rpc` remains the escape hatch for anything not wrapped: it is the
+  generated Connect client, and `SysMLService` is exported for a caller
+  building its own.
 
 ## Examples
 
@@ -400,9 +715,12 @@ npm run example 03        # one, by number or name
 ## Conformance
 
 The suite in `conformance/` is the service contract, and this client runs it
-**through its public API** — `load`/`loads`, `eval`, `symbol`, `instantiate` —
-not through the generated stubs. A scenario whose RPC v1 does not cover is
-skipped with a reason, and the report has the same shape `tools/cmd/conformance` emits:
+**through its public API** — `load`/`loads`, `parseSources`, `eval`, `symbol`,
+`instantiate`, `executeAction`, `convert`, `migrate`, `applyEdits`, `verifyConstraint`,
+`query`, `runDocumentQuery`, `renderDocument`, `runAnalysis`, `runSweep`,
+`listEngines` — not through the generated stubs. The only scenarios skipped are
+the ones whose request the public API refuses eagerly rather than asking the
+service, and the report has the same shape `tools/cmd/conformance` emits:
 
 ```bash
 npm run conformance -- --allow-skips --report report.json
@@ -410,14 +728,19 @@ npm run conformance -- --allow-skips --report report.json
 
 | protocol | ran | passed | failed | skipped |
 | --- | --: | --: | --: | --: |
-| `grpc` | 59 | 23 | 0 | 36 |
-| `connect` | 59 | 23 | 0 | 36 |
-| `connect-json` | 59 | 23 | 0 | 36 |
-| **total** | **177** | **69** | **0** | **108** |
-
-The 36 skips per protocol are 35 scenarios for the 10 RPCs listed above plus one
-the public API cannot express: a `ParseFile` naming no source, since `load` and
-`loads` always name one. Every skip carries its reason in the report.
+| `grpc` | 166 | 163 | 0 | 3 |
+| `connect` | 166 | 163 | 0 | 3 |
+| `connect-json` | 166 | 163 | 0 | 3 |
+| **total** | **498** | **489** | **0** | **9** |
+
+The 3 skips per protocol are the requests the public API cannot express because
+it validates them before calling: a `ParseFile` naming no source (`load` and
+`loads` always name one), a `ParseSources` naming no document and a
+`ParseSources` naming two documents alike (`parseSources` refuses both). Every
+skip carries its reason in the report. A refusal the client makes before asking,
+in the service's own words and with the status the service would answer — a v1
+model offered to `convert`, a v2 one to `migrate` — is reported as that status,
+so those scenarios run rather than skip.
 
 **The runner is not vacuous.** `--mutate <name>` corrupts a response on its way
 through the client, and each mutation makes at least one scenario fail:
@@ -452,10 +775,9 @@ commands, plus the mutation checks and a stub-drift check, in both
 
 ## Release
 
-Nothing here is published yet; the procedure is in
-[docs/project/releasing.md](../../docs/project/releasing.md) under "Releasing
-@openmbee/opensysml to npm". In short: the core `v*` tag's `release` workflow
-publishes this package and its five per-platform packages at the version
+The package and its five per-platform `sysml-grpc` packages are published to npm with each core
+`v*` release. The procedure is in [docs/project/releasing.md](../../docs/project/releasing.md)
+under "Releasing @openmbee/opensysml to npm". The `release` workflow publishes at the version
 `client/python/opensysml/_version.py` declares, carrying the release's own
 `sysml-grpc` binaries. The granular npm token it needs already lives in the
 `npm` context; granular tokens expire after at most 90 days, so rotation before

package/dist/browser/index.d.ts

@@ -1,9 +1,18 @@
 import { Connection } from "../core/connection.js";
 import type { TransportOptions } from "../core/connection.js";
 export * from "../core/index.js";
+export { connectWasm } from "./wasm.js";
+export type { BrowserWasmConnectOptions } from "./wasm.js";
 /** How a browser connects: the address is required, because nothing can be started. */
 export interface BrowserConnectOptions extends TransportOptions {
     address: string;
+    /**
+     * Release tag the service must report. 'latest' cannot be resolved in a
+     * browser, so it requires nothing.
+     */
+    version?: string;
+    /** Capabilities the service must report for the connection to be returned. */
+    requireCapabilities?: readonly string[];
 }
 /**
  * Connects to a running service. The service must allow this page's exact origin

package/dist/browser/index.js

@@ -5,6 +5,7 @@ import { Connection } from "../core/connection.js";
 import { OpenSysMLError } from "../core/errors.js";
 import { baseUrl, encodingOf, interceptors, timeoutOf } from "../core/transport.js";
 export * from "../core/index.js";
+export { connectWasm } from "./wasm.js";
 /**
  * Connects to a running service. The service must allow this page's exact origin
  * (`-cors-allowed-origins`) and, from an HTTPS page, must be served over TLS.
@@ -21,6 +22,9 @@ export async function connect(options) {
         useBinaryFormat: encoding === "protobuf",
         interceptors: interceptors(options),
     });
+    const required = options.version === undefined || options.version === "" || options.version === "latest"
+        ? undefined
+        : options.version;
     return Connection.open({
         transport,
         encoding,
@@ -28,7 +32,19 @@ export async function connect(options) {
             origin: url,
             // Nothing to release: the page never owned the service.
             release: () => Promise.resolve(),
+            warn: (message) => {
+                console.warn(message);
+            },
         },
         timeoutMs,
+        ...(required === undefined ? {} : { requiredVersion: required }),
+        ...(options.requireCapabilities === undefined
+            ? {}
+            : { requiredCapabilities: options.requireCapabilities }),
+        stale: {
+            address: url,
+            remedy: `point this page at a sysml-grpc that reports ${required ?? "a matching release"}, ` +
+                `or accept what is running by omitting version`,
+        },
     });
 }

package/dist/browser/wasm-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/browser/wasm-worker.js

@@ -0,0 +1,2 @@
+import { serveWasmPort } from "../core/wasm.js";
+serveWasmPort(globalThis);

package/dist/browser/wasm.d.ts

@@ -0,0 +1,17 @@
+import { Connection } from "../core/connection.js";
+import type { TransportOptions } from "../core/connection.js";
+/** Options for connecting to a Go WebAssembly module in a browser. */
+export interface BrowserWasmConnectOptions extends TransportOptions {
+    /** Module URL, response, bytes, or a compiled WebAssembly module. */
+    wasm: string | URL | Response | ArrayBuffer | Uint8Array | WebAssembly.Module;
+    /** wasm_exec.js from the Go toolchain that built the module. */
+    wasmExec?: string | URL;
+    /** A worker running the package's browser WASM worker entry point. */
+    worker?: Worker;
+    version?: string;
+    requireCapabilities?: readonly string[];
+}
+/**
+ * Connects to sysml-wasm inline, or in the provided worker.
+ */
+export declare function connectWasm(options: BrowserWasmConnectOptions): Promise<Connection>;

package/dist/browser/wasm.js

@@ -0,0 +1,94 @@
+import { Connection } from "../core/connection.js";
+import { connectWasmHost, instantiateInline, loadGoConstructor, loadWasmSource, WorkerWasmHost, } from "../core/wasm.js";
+/**
+ * Connects to sysml-wasm inline, or in the provided worker.
+ */
+export async function connectWasm(options) {
+    const host = options.worker === undefined
+        ? await startInline(options.wasm, options.wasmExec)
+        : await startWorker(options.worker, options.wasm, options.wasmExec);
+    return connectWasmHost(host, options);
+}
+async function startInline(wasm, wasmExec) {
+    const module = await browserWasmSource(wasm);
+    const Go = await loadGoConstructor(wasmExec === undefined ? undefined : resourceUrl(wasmExec));
+    return instantiateInline(module, Go);
+}
+async function startWorker(worker, wasm, wasmExec) {
+    const host = new WorkerWasmHost(browserWorkerEndpoint(worker));
+    try {
+        const { source, transfer } = await workerSource(wasm);
+        return await host.start({
+            type: "init",
+            wasm: source,
+            ...(wasmExec === undefined ? {} : { wasmExec: resourceUrl(wasmExec) }),
+        }, transfer);
+    }
+    catch (error) {
+        await host.close();
+        throw error;
+    }
+}
+function browserWorkerEndpoint(worker) {
+    return {
+        post(message, transfer) {
+            worker.postMessage(message, [...transfer]);
+        },
+        onMessage(listener) {
+            worker.addEventListener("message", (event) => {
+                listener(event.data);
+            });
+        },
+        onFailure(listener) {
+            worker.addEventListener("error", (event) => {
+                listener(new Error(event.message || "the sysml-wasm worker failed"));
+            });
+            worker.addEventListener("messageerror", () => {
+                listener(new Error("the sysml-wasm worker sent an unreadable message"));
+            });
+        },
+        terminate() {
+            worker.terminate();
+        },
+    };
+}
+async function workerSource(wasm) {
+    if (wasm instanceof WebAssembly.Module) {
+        return { source: wasm, transfer: [] };
+    }
+    if (wasm instanceof Response) {
+        if (wasm.bodyUsed) {
+            throw new Error("the WebAssembly Response body has already been read");
+        }
+        const bytes = await wasm.arrayBuffer();
+        return { source: bytes, transfer: [bytes] };
+    }
+    if (wasm instanceof ArrayBuffer) {
+        const bytes = wasm.slice(0);
+        return { source: bytes, transfer: [bytes] };
+    }
+    if (wasm instanceof Uint8Array) {
+        const bytes = Uint8Array.from(wasm).buffer;
+        return { source: bytes, transfer: [bytes] };
+    }
+    const url = wasm instanceof URL ? wasm.href : resourceUrl(wasm);
+    return { source: url, transfer: [] };
+}
+async function browserWasmSource(wasm) {
+    if (wasm instanceof WebAssembly.Module ||
+        wasm instanceof ArrayBuffer ||
+        wasm instanceof Uint8Array) {
+        return wasm;
+    }
+    if (wasm instanceof Response && wasm.bodyUsed) {
+        throw new Error("the WebAssembly Response body has already been read");
+    }
+    return loadWasmSource(wasm instanceof Response ? wasm : wasm instanceof URL ? wasm : resourceUrl(wasm));
+}
+function resourceUrl(value) {
+    if (value instanceof URL) {
+        return value.href;
+    }
+    const base = typeof document === "undefined" ? import.meta.url : document.baseURI;
+    return new URL(value, base).href;
+}

package/dist/core/arguments.d.ts

@@ -0,0 +1,4 @@
+/** Refuses `value` that is not a string, naming the parameter it was passed as. */
+export declare function requireString(param: string, value: unknown): asserts value is string;
+/** Refuses `value` that is not a string, or one whose lone surrogates cannot be sent. */
+export declare function requireSourceText(param: string, value: unknown): asserts value is string;

package/dist/core/arguments.js

@@ -0,0 +1,19 @@
+// Guards the public entry points reach before any call: a non-string argument
+// is refused as a TypeError, and source text a lone UTF-16 surrogate makes
+// unsendable is refused as a RangeError, as Python's client refuses them.
+// One half of a surrogate pair without the other (a high surrogate followed by
+// anything but a low surrogate, or a low surrogate not led by a high one).
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+/** Refuses `value` that is not a string, naming the parameter it was passed as. */
+export function requireString(param, value) {
+    if (typeof value !== "string") {
+        throw new TypeError(`${param} must be a string, got ${value === null ? "null" : typeof value}`);
+    }
+}
+/** Refuses `value` that is not a string, or one whose lone surrogates cannot be sent. */
+export function requireSourceText(param, value) {
+    requireString(param, value);
+    if (LONE_SURROGATE.test(value)) {
+        throw new RangeError(`${param} contains a lone UTF-16 surrogate, which cannot be sent to the service`);
+    }
+}