@ferscloud/fers-calculation-web 0.2.59 → 0.2.61

package/README.md

@@ -185,8 +185,31 @@ const mr = res.result.results.loadcases["…"].member_results["1"];
 
 Off by default to keep the payload lean; omitted from `member_results` when not requested.
 
+## Attribution
+
+Free-tier results carry an `attribution` object minted inside the solver.
+Premium results (solved with a valid solve token) do not, so the same code
+credits FERS on the free tier and white-labels on Pro:
+
+```ts
+import { fersAttributionHtml } from "@ferscloud/fers-calculation-web/badge";
+
+// "" when the result came back from a Pro solve.
+const credit = fersAttributionHtml(res);
+```
+
+`getFersAttribution`, `fersAttributionText` and `createFersBadge` are also
+exported. All of them accept the envelope, the parsed model or the results
+bundle, and all return nothing for a Pro result or an error envelope.
+
+Using the free tier in an application? Please display the credit. It is the
+only thing the free tier asks of you.
+
 ## Links
 
-- [Full documentation & getting started](https://ferscloud.com/getting-started)
+- [Structural analysis in JavaScript](https://ferscloud.com/structural-analysis-javascript) — why run the solver client-side
+- [JavaScript documentation](https://ferscloud.com/docs/javascript) — bundler setup, error codes, types, solve tokens
+- [Full documentation](https://ferscloud.com/getting-started) — every route into FERS
+- [llms-full.txt](https://ferscloud.com/llms-full.txt) — the whole documentation in one fetch, for agents
 - [FERS Cloud](https://ferscloud.com)
-- [FERS_core Python package](https://pypi.org/project/fers-core/)
+- [FERS Python package](https://pypi.org/project/fers/) — `pip install FERS`

package/badge.d.ts

@@ -0,0 +1,33 @@
+/** Free-tier provenance stamp. Absent from Premium results. */
+export interface FersAttribution {
+  /** Always "FERS". */
+  generated_by: string;
+  /** Canonical product URL. */
+  url: string;
+  /** Engine version that produced the results. */
+  engine_version: string;
+  /** Always "free" — Premium results carry no attribution at all. */
+  tier: string;
+  /** Plain-text credit. */
+  text: string;
+  /** Ready-to-inject HTML anchor. */
+  html: string;
+}
+
+/**
+ * Find the attribution object in a solver envelope, a parsed model, or a
+ * results bundle. Returns null for Premium results and for error envelopes.
+ */
+export function getFersAttribution(input: unknown): FersAttribution | null;
+
+/** Ready-to-inject HTML anchor, or "" on Pro. */
+export function fersAttributionHtml(input: unknown): string;
+
+/** Plain-text credit, or "" on Pro. */
+export function fersAttributionText(input: unknown): string;
+
+/** A detached DOM element carrying the credit, or null on Pro. */
+export function createFersBadge(
+  input: unknown,
+  doc?: Document,
+): HTMLElement | null;

package/badge.js

@@ -0,0 +1,69 @@
+// Attribution helpers for @ferscloud/fers-calculation-web.
+//
+// Free-tier results carry an `attribution` object minted inside the solver;
+// Premium results (solved with a valid solve token) do not. Everything here
+// returns nothing when the field is absent, so the same code shows a credit on
+// the free tier and white-labels on Pro with no flag to set and no branch to
+// write.
+//
+// Deliberately framework-free: a solver package should not drag in React. Use
+// `fersAttributionHtml()` with your framework's raw-HTML escape hatch, or
+// `createFersBadge()` if you would rather be handed a DOM node.
+//
+// Shipped only with the browser package. The Node build is server-side, where
+// a badge has nothing to render into — read `attribution.text` directly there.
+
+/**
+ * Find the attribution object, accepting whichever shape you happen to hold:
+ * the solver envelope, the parsed model, or the results bundle itself.
+ * @returns {{generated_by: string, url: string, engine_version: string, tier: string, text: string, html: string} | null}
+ */
+export function getFersAttribution(input) {
+  if (!input || typeof input !== "object") return null;
+  // Envelope: { ok, result } — an error envelope has nothing to credit.
+  if ("ok" in input) return input.ok ? getFersAttribution(input.result) : null;
+  // Parsed model: { ..., results: ResultsBundle }
+  if (input.results) return getFersAttribution(input.results);
+  // Results bundle.
+  return input.attribution ?? null;
+}
+
+/** Ready-to-inject HTML anchor, or "" on Pro. */
+export function fersAttributionHtml(input) {
+  return getFersAttribution(input)?.html ?? "";
+}
+
+/** Plain-text credit, or "" on Pro. Use for text reports and console output. */
+export function fersAttributionText(input) {
+  return getFersAttribution(input)?.text ?? "";
+}
+
+/**
+ * Build a detached DOM element carrying the credit, or null on Pro.
+ * @param {object} input solver envelope, model, or results bundle
+ * @param {Document} [doc] defaults to the global document
+ * @returns {HTMLElement | null}
+ */
+export function createFersBadge(input, doc) {
+  const attribution = getFersAttribution(input);
+  if (!attribution) return null;
+
+  const d = doc ?? (typeof document !== "undefined" ? document : null);
+  if (!d) return null;
+
+  const el = d.createElement("span");
+  el.className = "fers-attribution";
+  el.style.fontSize = "12px";
+  el.style.opacity = "0.75";
+
+  const a = d.createElement("a");
+  a.href = attribution.url;
+  a.target = "_blank";
+  a.rel = "noopener";
+  // textContent, not innerHTML: the string comes from the solver, but building
+  // the node by hand keeps this helper injection-proof by construction.
+  a.textContent = attribution.text;
+
+  el.appendChild(a);
+  return el;
+}

package/fers-models.d.ts

@@ -56,6 +56,11 @@ export interface components {
         AnalysisOptions: {
             /** Format: double */
             axial_slack?: number;
+            /**
+             * @description Declarative only; the solver always assembles the full 3D formulation.
+             *     A planar model must restrain its out-of-plane DOFs at every node itself
+             *     — see [`Dimensionality`].
+             */
             dimensionality: components["schemas"]["Dimensionality"];
             /**
              * @description When true, the engine generates self-weight (dead load) for every member
@@ -225,6 +230,16 @@ export interface components {
          *     results are reported in `results.buckling_runs` (with
          *     `results.buckling` carrying the first successful run for backward
          *     compatibility).
+         *
+         *     **The eigenvalue is mesh-sensitive, unlike the rest of the bundle.**
+         *     Reactions and the internal forces recovered along a member come out exact on
+         *     one element for a straight prismatic member; α_cr does not. A buckling
+         *     half-wave cannot form on a single cubic element — its consistent geometric
+         *     stiffness gives `12EI/L²` against Euler's `π²EI/L²`, so α_cr comes out about
+         *     **21 % high, which is unconservative**. Two elements per member are within
+         *     0.75 %, four within 0.05 %. Mesh compressed members into at least four
+         *     elements; the solve stays in the millisecond range. A run left on one element
+         *     raises `buckling_unrefined_mesh` in [`crate::models::results::modalresult::BucklingResults::warnings`].
          */
         BucklingAnalysisSettings: {
             /**
@@ -494,7 +509,21 @@ export interface components {
          */
         DensityUnit: "kg/m3" | "kg/mm3";
         /**
-         * @description Python:
+         * @description **Declarative only — the solver does not branch on this.** The formulation
+         *     is always the full 3D beam with 6 structural DOFs (plus warping) per node,
+         *     whichever value is given.
+         *
+         *     So a planar model is planar only because the caller made it so: it must
+         *     restrain the out-of-plane DOFs — `Z`, `RX` and `RY` for an XY model — on
+         *     **every node**, not just at the supports. Leave them free and the
+         *     out-of-plane subsystem is unrestrained, which is either a singular stiffness
+         *     matrix or, worse, a solve that succeeds with movement nobody asked for; see
+         *     the `singular_model` diagnostic.
+         *
+         *     The field is required because the payload has to carry something, and it is
+         *     kept because dropping it would break every existing caller for no gain.
+         *
+         *     Python:
          *     class Dimensionality(Enum):
          *         TWO_DIMENSIONAL = "2D"
          *         THREE_DIMENSIONAL = "3D"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ferscloud/fers-calculation-web",
   "type": "module",
-  "version": "0.2.59",
+  "version": "0.2.61",
   "license": "BSD-3-Clause",
   "repository": {
     "type": "git",
@@ -12,15 +12,47 @@
     "fers_calculations.js",
     "fers_calculations_bg.js",
     "fers_calculations.d.ts",
-    "fers-models.d.ts"
+    "fers-models.d.ts",
+    "badge.js",
+    "badge.d.ts"
   ],
   "main": "fers_calculations.js",
-  "homepage": "https://ferscloud.com",
+  "homepage": "https://ferscloud.com/structural-analysis-javascript",
   "types": "fers_calculations.d.ts",
   "sideEffects": [
     "./fers_calculations.js",
     "./snippets/*"
   ],
+  "description": "Structural analysis FEM solver for beams, frames and trusses, compiled from Rust to WebAssembly. Runs in the browser or in Node with no server round-trip. Includes Eurocode EN 1993-1-1 steel checks.",
+  "keywords": [
+    "structural-analysis",
+    "structural-engineering",
+    "finite-element",
+    "finite-element-analysis",
+    "fem",
+    "fea",
+    "solver",
+    "beam",
+    "frame",
+    "truss",
+    "stiffness-matrix",
+    "bending-moment",
+    "shear-force",
+    "deflection",
+    "buckling",
+    "eurocode",
+    "en1993",
+    "steel-design",
+    "wasm",
+    "webassembly",
+    "rust",
+    "engineering",
+    "civil-engineering",
+    "cad"
+  ],
+  "bugs": {
+    "url": "https://github.com/Jeroen124/FERS_calculations/issues"
+  },
   "publishConfig": {
     "access": "public"
   }