@ferscloud/fers-calculation-web 0.2.39 → 0.2.42

package/README.md

@@ -2,25 +2,82 @@
 
 High-performance structural engineering FEM solver compiled from Rust to WebAssembly. Runs entirely in the browser — no server round-trip per calculation.
 
+> This README covers both published packages: **`@ferscloud/fers-calculation`** (Node.js / server-side, `--target nodejs`) and **`@ferscloud/fers-calculation-web`** (browser / bundler, `--target bundler`). The API is identical; only installation and bundler setup differ.
+
 ## Installation
 
 ```bash
+# Browser apps (Vite, Next.js, webpack):
+npm install @ferscloud/fers-calculation-web
+# Node.js / server-side:
 npm install @ferscloud/fers-calculation
 ```
 
-## Quick start — free tier (up to 100 members)
+## Bundler setup (browser build)
+
+`@ferscloud/fers-calculation-web` is a WASM ES module that initialises via top-level `await`. Most bundlers need a one-time config:
+
+**Vite**
+
+```bash
+npm i -D vite-plugin-wasm vite-plugin-top-level-await
+```
 
 ```ts
-import init, { calculate_from_json } from "@ferscloud/fers-calculation";
+// vite.config.ts
+import wasm from "vite-plugin-wasm";
+import topLevelAwait from "vite-plugin-top-level-await";
 
-await init(); // load the WASM module once
+export default { plugins: [wasm(), topLevelAwait()] };
+```
 
-const result = calculate_from_json(JSON.stringify(myModel));
-const data = JSON.parse(result);
+**Next.js / webpack**
+
+```js
+// next.config.js
+module.exports = {
+  transpilePackages: ["@ferscloud/fers-calculation-web"],
+  webpack(config) {
+    config.experiments = { ...config.experiments, asyncWebAssembly: true };
+    config.output.environment = { ...config.output.environment, asyncFunction: true };
+    return config;
+  },
+};
+```
+
+The solver is synchronous and CPU-bound; for large models run it inside a Web Worker so the UI thread stays responsive. The Node.js package (`@ferscloud/fers-calculation`) needs no bundler config.
+
+## Quick start — free tier (up to 100 members)
+
+```ts
+import { calculate_from_json } from "@ferscloud/fers-calculation";
+
+// No init() call needed — the nodejs and bundler builds initialise the
+// WASM module automatically on import.
+const res = JSON.parse(calculate_from_json(JSON.stringify(myModel)));
+if (res.ok) {
+  const data = res.result; // displacements, member_results, unity_checks, …
+} else {
+  console.error(res.error.code, res.error.message);
+}
 ```
 
 No API key required. Works for any model with up to 100 members.
 
+## Response shape
+
+Every solver call returns a JSON **envelope**, so you `JSON.parse` once and branch on `ok` — you never have to sniff whether the returned string "looks like" an error:
+
+```jsonc
+// success
+{ "ok": true,  "result": { /* the full result document */ } }
+// failure (invalid model, over the member limit, malformed JSON, …)
+{ "ok": false, "error": { "code": "LimitExceeded",
+                          "message": "Number of members (250) exceeds allowed maximum of 100" } }
+```
+
+`error.code` is one of `InvalidJson`, `LimitExceeded`, `SolveError`, `InternalPanic`, `InternalSerialization`. The return value is **always** valid JSON.
+
 ## Authenticated tier — Pro (up to 10 000 members)
 
 Pro limits are unlocked by passing a short-lived signed token issued by the FERS Cloud server. The token is verified inside the WASM using an Ed25519 public key baked into the binary — it cannot be forged.
@@ -74,17 +131,16 @@ Same pattern works for Express, Deno, Bun, Cloudflare Workers, or any server-sid
 ### 3. Frontend: call the solver with the token
 
 ```ts
-import init, { calculate_from_json_with_token } from "@ferscloud/fers-calculation";
-
-await init();
+import { calculate_from_json_with_token } from "@ferscloud/fers-calculation";
 
 const { token } = await fetch("/api/solve-token").then(r => r.json());
 
-const result = calculate_from_json_with_token(JSON.stringify(myModel), token);
-const data = JSON.parse(result);
+const res = JSON.parse(calculate_from_json_with_token(JSON.stringify(myModel), token));
+if (!res.ok) throw new Error(`${res.error.code}: ${res.error.message}`);
+const data = res.result;
 ```
 
-If the token is missing, expired, or invalid, the solver falls back to the free 100-member limit — it never throws.
+If the token is missing, expired, or invalid, the solver falls back to the free 100-member limit — it never throws (a genuine solve failure comes back as `{ ok: false, error }`, not an exception).
 
 ## Tier comparison
 
@@ -99,6 +155,36 @@ If the token is missing, expired, or invalid, the solver falls back to the free
 
 Keep your `FERS_API_KEY` server-side only. The solve token it fetches is safe to pass to the browser — it is short-lived and cryptographically signed. Only FERS Cloud can issue valid tokens; the browser WASM can only verify them.
 
+## TypeScript types
+
+The browser package ships generated model types alongside the function signatures:
+
+```ts
+import type { FERS, ResultsBundle } from "@ferscloud/fers-calculation-web/fers-models";
+```
+
+`FERS` is the input model; `ResultsBundle` is the `result` payload of a successful envelope. Both are generated from the engine's OpenAPI schema, so they track the published version.
+
+## Deflected shape (optional)
+
+Set `include_member_deflected_shape` in the model's analysis options to get a
+ready-to-plot, **load-exact** deflected shape per member — the member's global
+displacement sampled along its length — instead of reconstructing the curve yourself:
+
+```ts
+const model = {
+  /* … model + load cases … */
+  analysis: { /* … */ options: { /* … */ include_member_deflected_shape: true } },
+};
+
+const res = JSON.parse(calculate_from_json(JSON.stringify(model)));
+const mr = res.result.results.loadcases["…"].member_results["1"];
+// mr.member_displacements: [{ x_frac, displacement: [dx, dy, dz] }, …]
+//   x_frac 0→1 along the member; displacement in the global input frame.
+```
+
+Off by default to keep the payload lean; omitted from `member_results` when not requested.
+
 ## Links
 
 - [Full documentation & getting started](https://ferscloud.com/getting-started)